@voxgig/sdkgen 4.20.0 → 4.22.0

package/project/.sdk/src/cmp/ts/Config_ts.ts

@@ -43,9 +43,6 @@ 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 ff = Path.normalize(__dirname + '/../../../src/cmp/ts/fragment/')
@@ -53,7 +50,6 @@ const Config = cmp(async function Config(props: any) {
   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)
   const authBasic = isHttpBasicAuth(model)
   // `in` and `name` travel with the prefix now. They were resolved by
@@ -74,30 +70,17 @@ const Config = cmp(async function Config(props: any) {
     `
     : ''
 
-  // Templated server URL: emit the spec's server-variable defaults so the
-  // runtime can substitute {name} placeholders in base (see makeOptions).
   const svars = serverVariables(model)
   const serverBlock = 0 === svars.length ? '' :
     'server: {\n' +
     svars.map((v: any) => `      ${JSON.stringify(v.name)}: ${JSON.stringify(v.dflt)},\n`).join('') +
     '    },\n\n    '
 
-  // Read the base URL here rather than leaving it to a `$$...$$` stdrep
-  // placeholder in the fragment. stdrep can only substitute a path the model
-  // actually has: a model with no `info.servers` left the placeholder itself in
-  // the generated source, so `options.base` came out as the literal string
-  // '$main.kit.info.servers.0.url$'. Reading it explicitly yields '' in that
-  // case, which is what every other target already emits, and is identical to
-  // the old output whenever the model does define a server.
   let baseUrl = ''
   try {
     baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`)
   } catch (_e) { }
 
-  // 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.
   const { def: configDef, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
@@ -125,9 +108,6 @@ const Config = cmp(async function Config(props: any) {
 
           '// #FeaturePlugins': () => pluginDefs(feature),
 
-          // A JS string literal, so the JSON survives verbatim. JSON.stringify
-          // escapes the quotes and backslashes the model contains (values like
-          // `$STRING` carry backticks, which a template literal could not).
           "'CONFIGJSON'": JSON.stringify(configJson),
         }
       })
@@ -165,8 +145,6 @@ const Config = cmp(async function Config(props: any) {
 
         '// #FeatureClasses': () => {
           each(feature, (f: any) => {
-            // Trailing comma: the map has one entry per feature, so entries
-            // must be comma-separated (a single feature hid this until now).
             Line(` ${f.name}: ${nom(f, 'Name')}Feature,`)
           })
         },
@@ -192,12 +170,6 @@ const Config = cmp(async function Config(props: any) {
           })
         },
 
-        // configDefinition's `def.entity` verbatim, NOT rebuilt here. This
-        // reduce was a second copy of that function's entityDefs loop, and
-        // when configDefinition started reconstructing a point's `parts`
-        // from apidef's segment vector (its ADR-003), only the data
-        // representation got it — the literal one emitted empty paths. The
-        // config-repr equivalence test caught it, which is what it is for.
         "'ENTITYMAP'": formatJson(configDef.entity, { margin: 2 }).trim(),
       }
     })
@@ -206,24 +178,8 @@ const Config = cmp(async function Config(props: any) {
 
 
 
-// PLUGIN DEFINITION IMPORTS AND THE FEATURE_PLUGINS MAP.
-//
-// 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 no longer
-// imports provider modules for their side effects — it imports each
-// active plugin's exported Definition BY NAME (the model's `def` map)
-// and hands the list to the feature through FEATURE_PLUGINS.
-//
-// Emitted here because Config already imports every active feature from
-// the model, and this is the same list one level down. The `def` map is
-// declared in the model rather than derived from filenames because one
-// file may export several definitions (sekreto's aws.ts exports
-// awssecrets AND awsparams).
 function pluginImports(feature: any) {
   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) => {
@@ -247,8 +203,6 @@ function pluginImports(feature: any) {
   })
 }
 
-// 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[] = []

package/project/.sdk/src/cmp/ts/EntityTypes_ts.ts

@@ -1,20 +1,5 @@
 
 
-// Typed-model generator (TypeScript reference target).
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one file, src/<Sdk>Types.ts,
-// with a TS `interface <Name>` per active entity plus a request/match type per
-// active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned into
-// real TS types by the shared sdkgen helper `canonToType` (source of truth:
-// @voxgig/apidef VALID_CANON).
-//
-// PORT RECIPE (language X): copy this file to EntityTypes_<X>.ts, keep the SAME
-// type-name scheme (<Name>, <Name>LoadMatch, <Name>ListMatch, <Name>CreateData,
-// <Name>UpdateData, <Name>RemoveMatch), swap the interface syntax for X's
-// struct/class/dataclass syntax, pass 'X' to canonToType, wire it into
-// Main_<X>.ts next to EntityBase, and reference the same type names from the
-// <X> op fragments + entity accessor.
 
 import {
   cmp, each, names,
@@ -32,7 +17,6 @@ import {
 const LANG = 'ts'
 
 
-// A valid TS property key, or a quoted string literal for anything else.
 function propKey(name: string): string {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name)
 }
@@ -41,10 +25,6 @@ function propKey(name: string): string {
 const EntityTypes = cmp(function EntityTypes(props: any) {
   const { model, log } = props.ctx$
 
-  // 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
@@ -56,9 +36,6 @@ 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 + 'Types.' + LANG }, () => {
@@ -74,13 +51,10 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 
     entityList.forEach((ent: any) => {
       const Name = ent.Name
-      // A TS/JS global (Record, Array, Promise, ...) would shadow itself
-      // for the rest of the file — see tsSafeTypeName.
       const TypeName = tsSafeTypeName(Name)
       const fields = (ent.fields ? each(ent.fields) : [])
         .filter((f: any) => f.active !== false)
 
-      // Entity data model: one property per field, `req:false` -> optional.
       Content(`export interface ${TypeName} {
 `)
       fields.forEach((f: any) => {
@@ -92,9 +66,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 
 `)
 
-      // Per active op: a request/match type. The members and each member's
-      // required/optional decision come from the shared partiality policy
-      // (opRequestShape); this file only renders them as a TS interface.
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {
@@ -112,11 +83,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 `)
         })
 
-        // Custom actions are selected with `$action` in the call's argument
-        // (see the Actions section of REFERENCE.md). Without it in the type,
-        // the ONLY documented way to reach those endpoints does not compile,
-        // and a TypeScript caller has to cast — which is how two of one API's
-        // six endpoints came to be unreachable from the typed interface.
         const actions = opActions(ops[opname])
         if (0 < actions.length) {
           Content(`

package/project/.sdk/src/cmp/ts/Entity_ts.ts

@@ -13,7 +13,6 @@ import {
 } from '@voxgig/apidef'
 
 import { EntityOperation } from './EntityOperation_ts'
-// import { EntityTest } from './EntityTest_ts'
 
 
 const Entity = cmp(function Entity(props: any) {
@@ -38,8 +37,6 @@ const Entity = cmp(function Entity(props: any) {
   // string stays entity.Name; only the TYPE reference is ever renamed.
   const dataType = tsSafeTypeName(entity.Name)
 
-  // Import exactly the typed models this entity references: its data type plus
-  // one request type per ACTIVE op (matches what EntityTypes_ts.ts emits).
   const typeNames = [dataType]
   const opnamesAll = Object.keys(entity.op || {})
   ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
@@ -76,8 +73,6 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           EntityDataType: dataType,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.ts so the class can be renamed independently.
           EntyClass: cls,
 
           '#TypeImports': ({ indent }: any) => Content({ indent }, typeImport),
@@ -95,7 +90,6 @@ if (fres instanceof Promise) { await fres }
     })
   })
 
-  // EntityTest({ target, entity, entrep, ff })
 })
 
 

package/project/.sdk/src/cmp/ts/Main_ts.ts

@@ -35,7 +35,6 @@ import { SdkError } from './SdkError_ts'
 
 const Main = cmp(async function Main(props: any) {
 
-  // Needs type: target object
   const { target } = props
   const { model } = props.ctx$
 
@@ -82,8 +81,6 @@ const Main = cmp(async function Main(props: any) {
         return Line(`import { ${cls} } from './entity/${cls}'`)
       })
 
-      // Re-export the generated typed models so consumers can
-      // `import { Advice, AdviceLoadMatch } from '<pkg>'`.
       Line(`export type * from './${model.const.Name}Types'\n`)
 
       Fragment(
@@ -92,14 +89,6 @@ const Main = cmp(async function Main(props: any) {
           replace: {
             ...props.ctx$.stdrep,
 
-            // SECRETS. All five slots are emitted only when the secrets
-            // feature applies to this target AND the model activates it.
-            // An unconditional edit here would land in every generated SDK
-            // and break the inactive-output gate: a model without the
-            // feature must generate byte-identically to pre-migration.
-            //
-            // `feature` is already gated by targetFeatures, so a target
-            // that does not provide 'sekreto' never reaches these.
             '// #SecretsImport': () => secrets ?
               Line(`import * as sekreto from './feature/secrets/sekreto'`) : undefined,
 
@@ -116,15 +105,6 @@ secrets() {
 }
 `) : undefined,
 
-            // prepare() bypasses the feature hook pipeline, so the PreSpec
-            // hook that resolves the secret for entity ops never runs on
-            // this path and the resolve has to be explicit.
-            //
-            // It RETURNS the Error rather than rejecting: _rawRequest
-            // awaits prepare() outside its try, and direct()/graphql() are
-            // documented to return a value or an Error, never reject. The
-            // prototype rejected here, which would have turned a broken
-            // vault into an unhandled rejection on the direct path.
             '// #SecretsResolve': ({ indent }: any) => secrets ?
               Content({ indent }, `
 if (null != this._secrets) {
@@ -164,7 +144,6 @@ if (fres instanceof Promise) { await fres }
           }
         },
 
-        // Entities
         () => {
           each(entity, (entity: ModelEntity) => {
             const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -173,13 +152,6 @@ if (fres instanceof Promise) { await fres }
           })
         })
 
-      // Station self-registration (station design §6.2 path 1;
-      // station-declarative-config §11 item 2): emitted ONLY when the model
-      // carries an ACTIVE station feature (installed via
-      // `package add @voxgig/sdkgen-station`). The library package name
-      // comes from the feature model's own `deps.ts` block — the same entry
-      // collectDeps flows into package.json — so the manifest dependency
-      // and the emitted require cannot disagree.
       const stationPkg = stationLibrary(model, target.name)
       if (null != stationPkg) {
         Fragment({

package/project/.sdk/src/cmp/ts/Package_ts.ts

@@ -14,6 +14,7 @@ import {
   packageVersion,
   authorInfo,
   targetFeatures, envName,
+  hasLiveScenarios,
 } from '@voxgig/sdkgen'
 
 
@@ -44,14 +45,11 @@ const Package = cmp(async function Package(props: any) {
   const only = (kind: string, deps: any) =>
     omap(deps, ([k, v]: any) => [v.active && kind === v.kind ? k : undefined, v.version])
 
-  // merge target and feature deps, by kind
   const deps =
     each(feature, (feature: any) =>
       omap(feature.deps?.[target.name], ([k, v]: any) =>
         [v.active ? k : undefined, v]))
 
-      // TODO: sort by version; rules for version choice?
-      // TODO: non-node dep kinds
       .reduce((a: any, deps: any) => (each(deps, (dep: any) =>
         a[dep.kind][dep.key$] = dep.version), a),
         {
@@ -75,37 +73,18 @@ const Package = cmp(async function Package(props: any) {
     type: 'commonjs',
     types: `dist/${SdkName}SDK.d.ts`,
 
-    // What actually ships. Without `files`, `npm publish` packs everything
-    // not gitignored — the test suite, dist-test/, the Makefile, the agent
-    // guides — into the published tarball. `src` IS included: the emitted
-    // .js.map files point back at it, so shipping it is what makes stack
-    // traces in a consumer resolve to SDK source. README/LICENSE/package.json
-    // are always included by npm and need no entry.
     files: ['dist', 'src'],
     scripts: {
-      ...(Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live))) ? {
+      ...(hasLiveScenarios(model) ? {
         'test:live': `npm run build && ${envName(model)}_TEST_LIVE=TRUE node --test dist-test/live.test.js`,
       } : {}),
 
-      // `test` and `test-coverage` run the COMPILED suite in dist-test/, which
-      // a fresh clone does not have — the glob then matches nothing and the
-      // run reports "tests 0, pass 0, fail 0" and exits 0. A green suite that
-      // asserted nothing is worse than a red one, so build first. npm runs a
-      // `pre<script>` automatically, which keeps the test commands readable
-      // and cannot be forgotten by a caller invoking `npm test` directly.
       'pretest': 'npm run build',
       'test': 'node --enable-source-maps --test-concurrency=1 --test \'dist-test/**/*.test.js\'',
       'test-some': 'node --enable-source-maps --experimental-test-isolation=none ' +
         '--test-name-pattern=\"$TEST_PATTERN\" --test \'dist-test/**/*.test.js\'',
       'test-utility': 'node --enable-source-maps --test test/utility/*.test.ts',
 
-      // Coverage gate. Runs the same suite with V8 coverage (no source-maps,
-      // so figures reflect true executed statements) over the SDK source
-      // only (test files excluded) and fails when coverage drops below the
-      // floor — protecting the runtime, utilities and features from silent
-      // regressions. Thresholds are a conservative floor (well under a
-      // healthy SDK's ~92% lines) so they hold across API shapes; raise them
-      // for a stricter local policy.
       'pretest-coverage': 'npm run build',
       'test-coverage': 'node --test-concurrency=1 --experimental-test-coverage ' +
         '--test-coverage-exclude=\'**/dist-test/**\' ' +
@@ -122,7 +101,6 @@ const Package = cmp(async function Package(props: any) {
     },
     author,
 
-    // TODO: needs to be config
     license: 'MIT',
 
     dependencies: deps.prod,
@@ -131,8 +109,6 @@ const Package = cmp(async function Package(props: any) {
   }
 
   File({ name: 'package.json' }, () => {
-    // Trailing newline: POSIX wants one, and without it every diff of a
-    // regenerated package.json reports "".
     Content(JSON.stringify(pkg, null, 2) + '\n')
   })
 })

package/project/.sdk/src/cmp/ts/PrepareAuth_ts.ts

@@ -12,51 +12,17 @@ import {
 } from '@voxgig/sdkgen'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated.
-//
-// This was a static file in `tm/ts/src/utility/` that hardcoded
-// `Authorization` and a 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. The result
-// was an SDK that sent a header the API does not read and never sent the
-// query parameter it does, so it could not authenticate at all. Four
-// repos in the cedar fleet shipped that way: joplin (`token`), pipedrive
-// (`api_token`), trello (`key`), lm-umbrella (`apiKey`).
-//
-// 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$
 
-  // The ONE signal that can honestly be honoured before runtime: the
-  // project saying "this SDK sends no credential, ever". Not
-  // `isAuthActive`, which is also false when the SPEC merely declares no
-  // scheme — those SDKs have always sent options.apikey.
   const suppressed = isAuthSuppressed(model)
   const where = resolveAuthIn(model)
-  // LOWERCASED FOR A HEADER, VERBATIM OTHERWISE. HTTP header names are
-  // case-insensitive on the wire, but the SDK's header map is a plain
-  // object keyed in lower case: the old template hardcoded
-  // `'authorization'`, the shared corpus asserts
-  // `ctx:spec:headers:authorization`, and every generatedcompile probe
-  // reads the lower-case key. apidef writes `name: "Authorization"`, so
-  // emitting it verbatim puts 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 resolvedName = resolveAuthName(model)
   const name = 'header' === where ? resolvedName.toLowerCase() : resolvedName
   const prefix = resolveAuthPrefix(model)
   const basic = isHttpBasicAuth(model)
 
-  // No `src` folder here: Main already opened it, and Config and SdkError
-  // write straight into it. Opening a second one puts the file at
-  // src/src/utility/ — where nothing imports it, and the stale copy at
-  // src/utility/ keeps being used.
   Folder({ name: 'utility' }, () => {
     File({ name: 'PrepareAuthUtility.' + target.ext }, () => {
       Content(render({ suppressed, where, name, prefix, basic }))
@@ -73,22 +39,6 @@ import { Context, Spec } from '../types'
 
 `
 
-  // NO GENERATION-TIME GATE ON WHETHER TO PLACE A CREDENTIAL AT ALL.
-  //
-  // The obvious move is to emit a no-op when `isAuthActive(model)` is
-  // false, and it is wrong. That is false whenever `main.kit.info.auth`
-  // is false — i.e. the SPEC declares no security scheme — but the SDK
-  // still carries a credential: `optspec` always declares `apikey`, and
-  // makeOptions fills `options.auth` from the optspec defaults, so the
-  // template's `null == options.auth` guard never actually fired and
-  // every such SDK has always sent `options.apikey`. Suppressing that at
-  // generation time silently breaks a working credential, which
-  // `auth null suppresses the credential` in generatedcompile catches,
-  // and takes the secrets feature down with it — the feature resolves a
-  // secret into options.apikey and prepareAuth then places nothing.
-  //
-  // `auth: null` is the DOCUMENTED suppression, it is a runtime value,
-  // and the runtime guard below is the one that honours it.
 
   // Auth switched off outright by the project. The credential-placing
   // body would be dead code, so it is not emitted — but the function
@@ -195,8 +145,6 @@ export {
 }
 
 
-// The bag the credential lands in, per placement. Cookies ride the header
-// bag because a cookie IS a header.
 function target(where: string): string {
   return 'query' === where ? 'query' : 'headers'
 }
@@ -209,9 +157,6 @@ function clear(where: string): string {
 
 function place(where: string): string {
   if ('query' === where) {
-    // NO PREFIX IN A QUERY STRING. `?token=Bearer%20abc` is not a thing any
-    // API reads; the prefix is a header convention and is dropped here
-    // deliberately rather than silently concatenated.
     return `    setprop(query, CRED_name, apikey)`
   }
 

package/project/.sdk/src/cmp/ts/ReadmeEntity_ts.ts

@@ -9,14 +9,6 @@ import {
 import { exampleValue } from './utility_ts'
 
 
-// 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('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
@@ -56,7 +48,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     const fields = entity.fields || []
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
-    // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
     const eVar = exampleVarName(entity.name, target.name)
 
     Content(`

package/project/.sdk/src/cmp/ts/ReadmeExampleTest_ts.ts

@@ -2,12 +2,6 @@
 import { cmp, Content, File } from '@voxgig/sdkgen'
 
 
-// Generates ts/test/ReadmeExample.test.ts — a test that reads the
-// repo's top-level README.md at runtime, extracts the first TS code
-// block under "## Quickstart", transforms `new <Name>SDK(...)`
-// to `<Name>SDK.test()` so it runs offline, evaluates the rest, and
-// asserts no error. Catches drift between the README quickstart and
-// the real SDK API.
 const ReadmeExampleTest = cmp(function ReadmeExampleTest(props: any) {
   const { ctx$: { model } } = props
   const Name = model.const.Name

package/project/.sdk/src/cmp/ts/ReadmeExamplesTest_ts.ts

@@ -7,31 +7,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Generates ts/test/readme_examples.test.ts — a COMPLETENESS GATE that
-// guarantees every fenced \`\`\`ts code example across all THREE docs (the
-// repo root README.md, this target's per-language README.md, and its
-// REFERENCE.md) is unit-tested. Every block from every doc is:
-//
-//  (1) TYPE-CHECKED against the real SDK types with the repo's local
-//      \`tsc --noEmit\`. To stay robust against tsc suppressing all semantic
-//      diagnostics program-wide whenever one file has a syntax error, blocks
-//      are compiled one-file-per-block in a fixpoint: compile the batch, drop
-//      the ones that error, recompile the rest, until a pass is clean — so a
-//      real type bug can never hide behind a neighbouring illustration's
-//      syntax error.
-//  (2) EXECUTED, if RUNNABLE (constructs \`new <Sdk>SDK\` / \`<Sdk>SDK.test\`
-//      or drives \`client.\`), by rewriting it to a seeded test-mode client
-//      and running it offline. A programming error (undefined method, wrong
-//      arity, bad symbol) fails; only a 404 / "Not found" domain error for an
-//      unseeded id is tolerated. This now runs for ALL THREE docs (previously
-//      only the root README executed).
-//  (3) PARTITIONED into exactly one of { executed, typechecked-only,
-//      illustration } with the counts asserted to sum to the total. A block
-//      that does NOT type-check is only allowed if it matches the NARROW
-//      illustration allowlist (bare method-signature \`?:\`, \`/* placeholder */\`
-//      value, or a type-SHAPE block). Any other non-type-checking block FAILS
-//      the test, quoting the block — it is NEVER silently skipped. A per-doc
-//      summary line makes the coverage visible in the test output.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { ctx$: { model } } = props
   const Name = model.const.Name

package/project/.sdk/src/cmp/ts/ReadmeHowto_ts.ts

@@ -14,12 +14,8 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Pick an entity with a real op (prefer a read op) — never fabricate a
-  // `load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
-  // only when NO entity exposes any op (a direct()-only SDK).
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
-  // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
   const eVar = exampleVarName(eName.toLowerCase(), 'ts')
 
   const primaryOpDef = exampleEntity && primaryOp && exampleEntity.op && exampleEntity.op[primaryOp]
@@ -30,7 +26,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const dataIdF = exampleEntity ? entityDataIdField(exampleEntity) : null
 
-  // A type-correct, language-idiomatic argument for the primary op call.
   const primaryArg = (idPlaceholder: string): string => {
     if (!exampleEntity || !primaryOp) return ''
     if ('list' === primaryOp) return ''
@@ -47,18 +42,18 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
           it.name === idF ? idPlaceholder : 'example_' + it.name)}`)
       return `{ ${pairs.join(', ')} }`
     }
-    // create / update: a body of the required writable fields.
+    const isIdField = (it: any) => it.name === idF || it.name === 'id'
     const items = opRequestShape(exampleEntity, primaryOp).items
-      .filter((it: any) => it.name !== idF && it.name !== 'id')
+      .filter((it: any) => !isIdField(it) || !it.optional)
     const required = items.filter((it: any) => !it.optional)
     const chosen = required.length ? required : items.slice(0, 3)
     const pairs = chosen.map((it: any) =>
-      `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`)
+      `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
+        isIdField(it) ? idPlaceholder : 'example_' + it.name)}`)
     return `{ ${pairs.join(', ')} }`
   }
   const testCallArg = primaryArg('test01')
   const stateCallArg = primaryArg('example')
-  // Only read `.id` off the returned record when its data type carries one.
   const stateDataLine = dataIdF
     ? `console.log(data.${dataIdF})`
     : `console.log(data)`

package/project/.sdk/src/cmp/ts/ReadmeIntro_ts.ts

@@ -33,13 +33,6 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const opList = (opNames.length ? opNames : ['list', 'load'])
     .map((o) => '`' + o + '`').join(', ')
 
-  // Sibling surfaces, MODEL-DRIVEN. This line used to hardcode "the CLI, and
-  // MCP server" — those are the `go-cli` and `go-mcp` targets, and this project
-  // has neither. So both per-language READMEs advertised surfaces nothing here
-  // generates, while the top-level Surfaces table (which does gate on active
-  // targets) listed only ts/ and go/. Name what is actually active, and drop
-  // the sentence entirely when this is the only surface, so it cannot outrun
-  // the model again.
   const targets = getModelPath(model, `main.${KIT}.target`) || {}
   const siblings = Object.entries(targets)
     .filter(([name, t]: any) => name !== target.name && false !== t.active)

package/project/.sdk/src/cmp/ts/ReadmeModel_ts.ts

@@ -30,9 +30,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const opRows = ['load', 'list', 'create', 'update', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
-  // Model-driven return-value bullets: describe only the operations that
-  // actually exist (single-object ops among load/create/update, plus
-  // list/remove) — never document return semantics for a missing op.
   const singleOps = ['load', 'create', 'update'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o + '`')
   const retBullets: string[] = []