@voxgig/sdkgen-infrapack 0.0.12 → 0.0.13

package/.sdk/src/cmp/seneca-provider/Main_seneca-provider.ts

@@ -21,36 +21,8 @@ import {
 import { Gitignore } from './Gitignore_seneca-provider'
 
 
-// The `seneca-provider` target: a Seneca plugin exposing this API's entities
-// as Seneca entities (`provider/<name>/<entity>`), layered on the sibling
-// `ts` SDK.
-//
-// A consumer target in the go-cli / py-data mould — every standard phase is
-// off in model/target/seneca-provider.aon and this component emits the
-// whole package. It differs from those in one way that shapes everything
-// here: it generates into ITS OWN REPO (`output: path`), depends on the SDK
-// as a PUBLISHED npm package rather than by path, and therefore carries a
-// repo's worth of furniture rather than a subfolder's.
-//
-// SHAPE OF THE MAPPING
-//
-// Seneca's store commands are list / load / save / remove. The SDK's are
-// list / load / create / update / remove. `save` is the one that is not
-// one-to-one: Seneca's convention is that an entity carrying an id is an
-// update and one without is a create, so `save` dispatches on `data.id`.
-//
-// Everything else follows from the model:
-//   - which cmds exist at all, from the entity's declared ops;
-//   - the required path params of each op, which become argument guards (a
-//     nested entity like `moon` under `/planet/{planet_id}/moon` cannot build
-//     its URL without the parent id, and an opaque 404 from a half-built URL
-//     is a bad error message);
-//   - the SDK accessor and entity class names, from the same helpers the ts
-//     target uses, so the two cannot drift.
-
-
-// Seneca store cmd -> the SDK ops it needs. `save` needs BOTH create and
-// update; it is emitted when either is present and dispatches on the id.
+
+
 const CMD_OPS: Record<string, string[]> = {
   list: ['list'],
   load: ['load'],
@@ -59,28 +31,6 @@ const CMD_OPS: Record<string, string[]> = {
 }
 
 
-// The custom ACTIONS one Seneca cmd can reach, as action name -> SDK op.
-//
-// apidef folds a non-CRUD verb into an ordinary op as an extra point marked
-// `select.$action`: GitHub's `PUT /repos/{owner}/{repo}/pulls/{n}/merge` is a
-// second point of `pull.update`, beside the canonical `PATCH`. The SDK
-// selects one with `$action` in the call's argument; without this map the
-// provider has no way to name one at all, and `merge` is simply unreachable
-// through a generated plugin.
-//
-// KEYED BY CMD, NOT BY OP, and that is the whole point of the function.
-// `save` covers create AND update, so an action folded into `create` arrives
-// through `save$` exactly as one folded into `update` does — assuming
-// `update` would send `upload_image` (petstore's
-// `POST /pet/{petId}/uploadImage`, a create point) to the wrong endpoint, and
-// the SDK would then refuse it as an invalid action on an operation the
-// caller never named.
-//
-// A name claimed by an earlier op WINS: `entityActions` walks the op map in
-// sorted-key order, so for `save` that is create before update. Two ops of
-// one entity sharing an action name is not something apidef produces from a
-// spec — the name comes from the route — and if it ever does, a stable choice
-// beats a last-writer-wins one.
 function cmdActions(ent: any, cmd: string): Record<string, string> {
   const ops = CMD_OPS[cmd] || []
 
@@ -107,21 +57,13 @@ function cmdActions(ent: any, cmd: string): Record<string, string> {
 }
 
 
-// The ops that have a route of their OWN, as opposed to nothing but folded-in
-// actions. An op whose every point is an action point has no plain call: a
-// `save$` naming no action still reaches the SDK's `update`, but the SDK finds
-// one point and takes it, so the "canonical" update IS the action's route.
-//
-// Which is what the generated tests need to know before writing a plain,
-// id-bearing save: without this they were emitted for an entity that has no
-// such call to make.
 function canonicalOps(ent: any): string[] {
   return entityOps(ent).filter((opname: string) => {
     const op = (ent.op || {})[opname]
     const points: any[] = (op && op.points) || []
 
     return points.some((pt: any) =>
-      null == (pt && pt.select && pt.select['$action']))
+      null == (pt && pt.q && pt.q['$action']))
   })
 }
 
@@ -146,9 +88,6 @@ function entityActionList(ent: any):
 }
 
 
-// The required (non-optional) request keys of an op, id first. These are what
-// the SDK needs to build the path, so they are what the provider must have
-// before it calls.
 function requiredKeys(ent: any, opname: string): string[] {
   const idf = entityIdField(ent)
   return opRequestShape(ent, opname).items
@@ -167,13 +106,6 @@ function addressKeys(ent: any, opname: string): string[] {
   const parts = idParts(ent)
 
   if (0 < parts.length) {
-    // EVERY PART, required or not — for the same reason a single record key
-    // always travels. github's api_insights_summary_stat is keyed
-    // `actor_type/actor_id` and declares both OPTIONAL, because the op also
-    // covers routes that take neither; only `min_timestamp` came through as
-    // required. So the call sent the timestamp alone, the split id went
-    // nowhere, and every read answered with the same record — the composite
-    // half of the defect fixed below for single keys.
     const shape = opRequestShape(ent, opname).items
     for (const part of parts) {
       if (!keys.includes(part) &&
@@ -194,33 +126,6 @@ function addressKeys(ent: any, opname: string): string[] {
 }
 
 
-// The key that addresses ONE record.
-//
-// `entityIdField` answers whenever the model declares one, which apidef does
-// for any entity carrying a field literally named `id` — and it renames an
-// `<entity>_id` path param to `id` besides, which is why most APIs never reach
-// the fallback.
-//
-// When it does NOT answer, the record key is the LAST path param of the
-// op's own point, in PATH order — a route addresses parents first and the
-// record last, by construction. Without this the key was simply unknown,
-// so a param named `code` failed the `!== idf` test in opParentKeys and
-// was classified as a PARENT — `load$('SAVE20')` threw "coupon load: code
-// is required" instead of loading anything, and the entity was treated as
-// nested throughout.
-//
-// opParams(op) is NOT the source here: it alphabetizes params for output
-// stability, which loses path order on a 3+-param route — Airtable's
-// record (base_id, table_id, record_id) alphabetizes with table_id last,
-// so the old `params[params.length - 1]` picked the wrong parent as the
-// record's own key. The point's own `parts` still has the true order.
-// The path parameters that TOGETHER name one record, when no single one does.
-//
-// apidef sets `id.parts` for an API that addresses a record by several
-// adjacent path parameters — github needs {owner} AND {repo} to name a
-// repository — and `id.sep` (a slash) joins them into the ONE id a Seneca
-// entity carries. Empty for the ordinary single-key entity, which is most of
-// them, so every caller can branch on `0 < parts.length`.
 function idParts(ent: any): string[] {
   const parts = ent?.id?.parts
   return Array.isArray(parts) && 1 < parts.length ?
@@ -234,18 +139,6 @@ function idSep(ent: any): string {
 }
 
 
-// THE ONE DESCRIPTION OF AN ENTITY'S ID, or null when Seneca's `id` and the
-// API's key already agree and nothing needs translating.
-//
-// It unifies the two cases that used to be handled by separate emitters. A
-// compound key (`{owner}/{repo}`) has several parts; an API that simply calls
-// its key something else (`repo`, `number`) has exactly one. Neither needs a
-// different algorithm — a one-part split is the identity, and a one-part join
-// is the old carry-across — so both come through the same table and the same
-// two functions.
-//
-// `from` is passed through as the model states it: which response field
-// carries each part. apidef derives it and guide.aon can correct it.
 function idSpec(ent: any): { parts: string[], sep: string, from?: Record<string, string> } | null {
   const parts = idParts(ent)
   if (0 < parts.length) {
@@ -262,8 +155,6 @@ function idSpec(ent: any): { parts: string[], sep: string, from?: Record<string,
     return null
   }
 
-  // A single-key entity whose key is not `id`. `from` defaults to the key's
-  // own name, which is what the old carry-across read.
   return { parts: [rk], sep: idSep(ent) }
 }
 
@@ -281,11 +172,8 @@ function recordKey(ent: any): string {
     }
 
     const canonical = op.points.filter((pt: any) =>
-      null == (pt && pt.select && pt.select['$action']))
+      null == (pt && pt.q && pt.q['$action']))
     const point = ownPoint(0 < canonical.length ? canonical : op.points)
-    // The LAST variable segment names the record's key. apidef states which
-    // segments are variables (its ADR-003), so this reads the name off the
-    // vector rather than finding a `{` and slicing the braces back off.
     const vars = pointSegments(point)
       .filter((seg: any) => null != seg.var)
 
@@ -293,12 +181,10 @@ function recordKey(ent: any): string {
       return String(vars[vars.length - 1].var)
     }
 
-    // No path param at all (e.g. GET /scan/async/result?trace_id=...): the
-    // record's own key can still be a single required QUERY param.
-    const query = (point && point.args && point.args.query) || []
-    const reqdQuery = query.filter((q: any) => false !== q.reqd)
+    const query = (point && point.g && point.g.query) || []
+    const reqdQuery = query.filter((q: any) => false !== q.r)
     if (1 === reqdQuery.length) {
-      return String(reqdQuery[0].name)
+      return String(reqdQuery[0].n)
     }
   }
 
@@ -306,25 +192,12 @@ function recordKey(ent: any): string {
 }
 
 
-// The guard function's name. Spec-derived param names are not constrained to
-// identifiers — Evervault's `/payments/3ds-sessions/{3ds_session_id}` is the
-// standing example — and a name is a DECLARATION here, so it cannot be
-// bracket-quoted the way a property access can. Non-identifier characters are
-// replaced rather than dropped, so `a-b` and `a_b` cannot collide.
 function guardName(e: any, key: string): string {
   return `need_${e.name}_${String(key).replace(/[^A-Za-z0-9_$]/g, '_')}`
     .replace(/^need_(\d)/, 'need__$1')
 }
 
 
-// The parent PATH params of ONE op: `moon`'s load under
-// `/planet/{planet_id}/moon/{id}` yields ['planet_id']. These are the keys a
-// caller can forget, so each gets a guard.
-//
-// From opParams — the op's declared path params — NOT from opRequestShape.
-// For create/update the latter also returns the request BODY fields, so
-// reading it here generated a "planet name is required" guard for every
-// writable field on every entity.
 function opParentKeys(ent: any, opname: string): string[] {
   const rk = recordKey(ent)
   const op = (ent.op || {})[opname]
@@ -336,8 +209,8 @@ function opParentKeys(ent: any, opname: string): string[] {
   const seen = new Set<string>()
 
   for (const p of opParams(op)) {
-    const name = String((p as any).name)
-    if (false !== (p as any).reqd && name !== rk && name !== 'id') {
+    const name = String((p as any).n)
+    if (false !== (p as any).r && name !== rk && name !== 'id') {
       seen.add(name)
     }
   }
@@ -346,13 +219,6 @@ function opParentKeys(ent: any, opname: string): string[] {
 }
 
 
-// Every parent key the entity has, across its ACTIVE ops — for the seed data
-// and the docs, which describe the entity rather than one call.
-//
-// `entityOps` and not `Object.keys(ent.op)`: an op the model marks
-// `active: false` generates no SDK method, so letting it contribute a key
-// here put a mandatory guard for a parameter of a call that does not exist
-// onto every cmd that does.
 function parentKeys(ent: any): string[] {
   const seen = new Set<string>()
 
@@ -366,20 +232,6 @@ function parentKeys(ent: any): string[] {
 }
 
 
-// A model field's broad shape, for generating seed data that reads as data.
-// The model carries canon strings (`\`$STRING\``), not JS types.
-//
-// ORDER MATTERS and the tests are substring tests, so the container kinds are
-// checked FIRST: a multi-type field's sentinel is the ARRAY
-// `['`$ONE`', [members...]]`, and String() flattens it to a comma-joined
-// string — so a `$ONE` of string|number matched `includes('NUMBER')` and was
-// seeded as a bare number. A union is not a number; it is whatever its first
-// member is, and falling back to a string is the safe answer.
-//
-// `$ARRAY` and `$OBJECT` are in the sentinel vocabulary (see
-// helpers/canonType.ts) and used to fall through to 'string', which put
-// `tags: 'quick-tags'` into test/quick.js — a type-incorrect body that a
-// validating server rejects.
 function fieldKind(type: any): string {
   if (Array.isArray(type)) {
     return 'string'
@@ -396,21 +248,12 @@ function fieldKind(type: any): string {
 }
 
 
-// Which entity a parent path param refers to: `planet_id` -> `planet`, but
-// only when an entity of that name actually exists. A key that names no
-// entity gets no cross-reference, and the seed falls back to a plain string.
 function parentEntityOf(key: string, names: string[]): string {
   const stem = key.replace(/_id$/, '')
   return names.includes(stem) ? stem : ''
 }
 
 
-// The repo this provider is released from — NOT the SDK's. A provider is its
-// own package in its own repo, so its manifest's homepage/repository must
-// point there; deriving them from `main: kit: repo` sends every link in the
-// published package to the SDK instead.
-//
-// Order: the project's `output: repo`, else the Seneca convention.
 function providerRepo(model: any, lower: string, tname: string):
   { url: string, path: string } {
   const host = model?.main?.[KIT]?.repo?.host || 'github.com'
@@ -437,9 +280,6 @@ const Main = cmp(function Main(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
-  // HARD REQUIREMENT: this plugin imports the TypeScript SDK. Generating it
-  // without `ts` produces a package whose every import fails, so fail at
-  // GENERATE time with an actionable message instead.
   const targets = model.main[KIT].target || {}
   if (null == targets.ts) {
     throw new SdkGenError(
@@ -449,12 +289,12 @@ const Main = cmp(function Main(props: any) {
       'then regenerate.')
   }
 
-  const Name = model.const.Name                 // Solardemo
-  const lower = String(model.const.name)        // solardemo
-  const ENV = envName(model)                    // SOLARDEMO
-  const sdkClass = `${Name}SDK`                 // SolardemoSDK
-  const pluginName = `${Name}Provider`          // SolardemoProvider
-  const fileBase = `${lower}-provider`          // solardemo-provider
+  const Name = model.const.Name
+  const lower = String(model.const.name)
+  const ENV = envName(model)
+  const sdkClass = `${Name}SDK`
+  const pluginName = `${Name}Provider`
+  const fileBase = `${lower}-provider`
 
   // The SDK is a PUBLISHED dependency, not a path: this package lives in its
   // own repo. Its name is whatever the ts target publishes under, pin
@@ -464,45 +304,23 @@ const Main = cmp(function Main(props: any) {
   const sdkPkg = packageName(model, 'npm')
   const sdkVersion = packageVersion(model, 'ts')
 
-  // UNFILTERED by design — see the AGENTS.md sharp edge: entityCollection is
-  // the resolver every component must use (getModelPath rebuilds its container
-  // per call, defeating the class-name memo), and it deliberately includes
-  // inactive entities because the typed-model emitters need them.
-  //
-  // Which makes filtering `active` the CALLER's job, and this component was
-  // the one consumer target that skipped it — go-cli, go-mcp and py-data all
-  // re-filter. The cost: MainEntity_ts emits an accessor only for an ACTIVE
-  // entity, so an inactive one produced `this.shared.sdk.Ghost()` in the
-  // provider and an `assert.equal(typeof sdk.Ghost, 'function')` in its tests,
-  // against a method the SDK does not have.
   const entityColl = entityCollection(model)
 
   const activeEntities = Object.keys(entityColl).sort()
     .map((key: string) => entityColl[key])
     .filter((ent: any) => false !== ent.active)
 
-  // Entities this provider can serve: those with at least one op that maps to
-  // a Seneca store cmd. An entity with no such op would produce an empty cmd
-  // map, which seneca-entity treats as a store that answers nothing.
   const entityNames = activeEntities.map((ent: any) => ent.name)
 
   const entities = activeEntities
     .map((ent: any) => {
       const parents = parentKeys(ent)
 
-      // The parent entity PER KEY. Deriving it from `parents[0]` alone left an
-      // entity nested two levels deep with no cross-reference for its outer
-      // parents, so their seed values came out as the literal '0'.
       const parentOf: Record<string, string> = {}
       for (const key of parents) {
         parentOf[key] = parentEntityOf(key, entityNames)
       }
 
-      // The parent keys of each op SEPARATELY. The guards used to be the union
-      // across all ops, applied to every cmd alike, while the argument handed
-      // to the SDK was computed per op — so an entity whose routes are not
-      // uniformly nested (a flat `load`, a nested `create`) demanded a
-      // parameter its own call would never use.
       const opParents: Record<string, string[]> = {}
       for (const opname of entityOps(ent)) {
         opParents[opname] = opParentKeys(ent, opname)
@@ -511,27 +329,11 @@ const Main = cmp(function Main(props: any) {
       return {
         ent,
         name: ent.name,
-        // The SDK ACCESSOR on the client (`client.Moon()`), which is the
-        // entity's PascalCase name — NOT entityClassName, which is the
-        // collision-safe CLASS name the accessor constructs (`MoonEntity`).
-        // Calling the class name reads plausibly and fails at runtime with
-        // "sdk.MoonEntity is not a function". MainEntity_ts is the authority
-        // for this: it declares the method as `${entity.Name}()`.
         acc: ent.Name,
-        // The entity's canonical route, used to probe the live server for
-        // liveness. Path params are left in place only if the route has
-        // them — a collection route (the `list` op's) has none, which is why
-        // entityPath prefers it.
         path: entityPath(ent),
         cls: entityClassName(ent, entityColl),
         ops: entityOps(ent),
         idf: entityIdField(ent),
-        // The field this API's routes actually ADDRESS a record by, which is
-        // not always `id` and is not always what entityIdField answers (that
-        // returns null when the load match has no `id`, leaving recordKey to
-        // read the route's last variable segment). The doc and test emitters
-        // in Extras need the same answer the handler emitters use, or the
-        // seed they build is keyed by a field the routes never look at.
         rk: recordKey(ent),
         // The composite key, when this API addresses a record by several
         // path params at once. The doc and test emitters in Extras need the
@@ -540,41 +342,6 @@ const Main = cmp(function Main(props: any) {
         // rejects.
         idparts: idParts(ent),
         idsep: idSep(ent),
-        // DOES EACH SINGLE-RECORD OP ACTUALLY CARRY THE RECORD'S KEY?
-        //
-        // Only then can a wrong id miss on a LOAD: github's `interaction`
-        // reads `/user/interaction-limits` — a singleton, called as
-        // `load({})` — so `load$('no-such-id')` correctly returns the one
-        // record there is, and a not-found test against it asserts the
-        // opposite of the truth.
-        //
-        // And only then can a REMOVE delete what a create just made. A
-        // tag-bucket entity can have ops addressing different resources
-        // entirely: github's `action` is keyed `archive_format` from its
-        // download route while its remove takes `hosted_runner_id` and
-        // `org_id`, so the remove addressed by parent scope alone — it
-        // deleted whichever record the store happened to yield first, which
-        // was usually a SEEDED one, and the round-trip failed on the record
-        // it had created surviving. Intermittently: the created record's id
-        // is random, so where it falls in iteration order decides.
-        //
-        // Parent keys alone do not distinguish records, which is why this
-        // asks for the record's key or every composite part rather than
-        // merely for "the route has a parameter".
-        // WHICH SINGLE-RECORD OPS ADDRESS A DIFFERENT RESOURCE ENTIRELY.
-        //
-        // Not merely "cannot address the record": an op that addresses
-        // NOTHING is a singleton read, and github's `interaction`
-        // (`/user/interaction-limits`) is a real one. This is the other case
-        // — the op addresses something, and it is not this record. Every one
-        // is a tag-derived entity whose ops were gathered from unrelated
-        // routes: `migration`'s remove takes `owner` and `repo` and deletes
-        // a repository's migration archive, `user`'s deletes a GPG KEY, and
-        // `pull`'s deletes a review COMMENT. The id the caller passed is
-        // dropped, and the request goes anyway.
-        //
-        // Reads are untouched across the whole of github — this is 7 removes
-        // and 5 updates, and both are writes.
         idmisaddressed: ['remove', 'update'].reduce(
           (acc: Record<string, boolean>, opname: string) => {
             acc[opname] = null != (ent.op || {})[opname] &&
@@ -594,8 +361,6 @@ const Main = cmp(function Main(props: any) {
               keys.includes(recordKey(ent))
             return acc
           }, {}),
-        // Where each part is carried in a response. The test emitter needs
-        // it to know whether a created record's id can be rebuilt at all.
         idfrom: (ent?.id?.from) || {},
         parents,
         parentOf,
@@ -613,30 +378,15 @@ const Main = cmp(function Main(props: any) {
             acc[cmd] = cmdActions(ent, cmd)
             return acc
           }, {}),
-        // The same information flattened, for the README and the generated
-        // tests: [{ cmd, op, action, path }].
         actionList: entityActionList(ent),
-        // The ops with a route of their own. `ops` minus those that are
-        // nothing but folded-in actions — what the generated tests consult
-        // before assuming a plain call exists.
         canonicalOps: canonicalOps(ent),
-        // Required fields only: a seed record has to satisfy the shape the
-        // SDK will hand back, and optional noise makes the assertions
-        // harder to read.
-        //
-        // A parent path param is then FORCED IN even when the entity's own
-        // schema omits it or marks it optional. A path param is a routing key,
-        // not necessarily a response field: when the child's schema left it
-        // out the seeded record had no link back to its parent, and the mock's
-        // match found nothing — which the nested `load` test reported as a
-        // TypeError and the nested `list` test reported as a pass.
         fields: (() => {
-          const req = (ent.fields || [])
-            .filter((f: any) => false !== f.req)
+          const req = (Object.values(ent.fields || {}))
+            .filter((f: any) => false !== f.r)
             .map((f: any) => ({
-              name: f.name,
-              kind: fieldKind(f.type),
-              parentEntity: parentEntityOf(f.name, entityNames),
+              name: f.n,
+              kind: fieldKind(f.t),
+              parentEntity: parentEntityOf(f.n, entityNames),
             }))
 
           const have = new Set(req.map((f: any) => f.name))
@@ -677,27 +427,6 @@ const Main = cmp(function Main(props: any) {
   // once by the external pass — see cmp/ExternalTarget.
   const sdkrel = ctx$.sdkrelpath || '..'
 
-  // WHERE THE SDK SOURCE IS, AND WHY IT IS NOT `sdkrel`.
-  //
-  // `sdkrel` is a walk back through the FILESYSTEM, and it is committed here
-  // — into the docs, the live-test headers and the develop-locally recipe.
-  // That makes generated content depend on one machine's directory layout.
-  // voxgig-solardemo-sdk committed '../../voxgig-sdk/voxgig-solardemo-sdk',
-  // where `voxgig-sdk` is the name of a workspace directory on one laptop and
-  // no part of any model; a second developer with both repos under a
-  // differently named parent regenerates a diff in tracked files and follows
-  // instructions that are wrong on one of the two machines.
-  //
-  // So the SDK is named by its PIN instead — repository and release tag, both
-  // facts about the SDK rather than about anyone's disk — and fetched to a
-  // fixed path INSIDE this repo. `make sdk-src` puts it there. The path is
-  // then the same string on every machine and under every layout, which is
-  // what lets this repo regenerate itself from a checkout it fetched (see
-  // SdkPin and the Makefile).
-  //
-  // The tag is `v<version>`: the SDK's publish workflow cuts exactly that for
-  // its primary npm target, so the pin needs no separate bookkeeping and
-  // cannot drift from the dependency version.
   const sdkRepoUrl = String(repoInfo(model).repoUrl || '')
   const sdkTag = 'v' + sdkVersion
   const sdkRepoDir = sdkRepoUrl.replace(/[/]+$/, '').split('/').pop() || 'sdk'
@@ -708,22 +437,6 @@ const Main = cmp(function Main(props: any) {
   const sdkPinned = '' !== sdkRepoUrl
   const sdkSrc = sdkPinned ? SDK_SRC_DIR + '/' + sdkRepoDir : sdkrel
 
-  // Where a live run points — and whether there is anything honest to point
-  // it at.
-  //
-  // NOT simply `servers[0].url`. For an OpenAPI-derived model that is the
-  // PRODUCTION host of a third-party API, and everything gated on it aims
-  // there: the `describe('live')` block, which `npm test` runs on every CI
-  // push on three operating systems; the `serverUp` probe in front of it; and
-  // test/quick.js, whose header says "start the companion server first" while
-  // BASE silently defaults to production and whose body is a create / update /
-  // remove cycle. A live suite that reaches a stranger's API from CI is not a
-  // live suite, it is traffic — and unauthenticated traffic at that.
-  //
-  // So a live base is taken only when it is unambiguously OURS: declared
-  // outright by the project, or a loopback address, which no third party can
-  // be behind. Anything else leaves live testing ungenerated, which is the
-  // honest answer for an API nobody here runs.
   const live = model?.main?.[KIT]?.test?.live || {}
   const servers = (model?.main?.[KIT]?.info?.servers || [])
   const specBase = 0 < servers.length ? String(servers[0].url || '') : ''
@@ -748,9 +461,6 @@ const Main = cmp(function Main(props: any) {
   const provider = {
     Name, lower, ENV, sdkClass, pluginName, fileBase,
     sdkPkg, sdkVersion, entities,
-    // The SDK dependency, resolved ONCE. PackageJson emits it and the CI
-    // note describes it, and computing it twice is how the second caller
-    // came to pass a half-built provider object into it.
     sdkDep,
     // Whether that dependency comes from outside a registry. The generated
     // CI note says so, because "npm install is all you need" stops being
@@ -761,60 +471,28 @@ const Main = cmp(function Main(props: any) {
     // that says the wrong one is worse than no note.
     sdkDepKind: sdkDep.startsWith('github:') ? 'git' :
       (sdkDep.startsWith('http') ? 'release' : 'npm'),
-    // THE OPT-IN A NON-REGISTRY DEPENDENCY NEEDS, or ''.
-    //
-    // npm 12 defaults `allow-git` and `allow-remote` to "none" and REFUSES
-    // such a dependency outright — EALLOWGIT / EALLOWREMOTE, before it
-    // fetches anything. Older npm allowed both, so a workflow that passes
-    // today fails the moment its runner image updates; this provider's own
-    // publish run failed that way within hours of the build run passing,
-    // because publishing upgrades npm first.
-    //
-    // Emitted ONLY where the project chose such a dependency: it is the
-    // project opting into what it already declared, not a default weakened
-    // for everyone. Publishing the SDK remains the durable answer, and this
-    // flag exists so an unpublished one is workable meanwhile.
     sdkInstallFlag: sdkDep.startsWith('github:') ? ' --allow-git=all' :
       (sdkDep.startsWith('http') ? ' --allow-remote=all' : ''),
     repoUrl: repo.url,
-    // The SDK's own repo, for pointing at the companion test server which is
-    // only distributed in source.
     sdkRepoUrl,
     sdkTag,
     sdkRepoDir,
     sdkPinned,
-    // Where the SDK SOURCE is reached, as every generated file spells it.
-    // Layout-independent when the SDK has a repo to pin. See above.
     sdkSrc,
     api: apiName(model),
     version: packageVersion(model, target.name),
     liveBase,
     liveApp,
-    // The sponsor line. @seneca/maintain's `content_readme` check requires
-    // the publisher's name in the README, so this is load-bearing rather
-    // than decorative — the generated `maintain` test fails without it.
     publisher: PUBLISHER,
     publisherUrl: PUBLISHER_URL,
-    // A route with NO path params, so the probe is a plain GET. An entity
-    // whose every route is parameterised gives none, and then the probe
-    // falls back to the base URL itself.
     probePath: (entities.find((e: any) =>
       '' !== e.path && !e.path.includes('{')) || { path: '' }).path,
-    // The provider's OWN published name. Not derived from the SDK slug the
-    // way a language target's is — a provider is `@seneca/<name>-provider` —
-    // so read the project's pin directly and default to that shape.
     pkgName: providerPackage(model, lower, target.name),
     // Whether this API authenticates at all. Decides if the plugin plumbs a
     // credential: the SDK's auth stage emits nothing for an auth-inactive
     // model and strips the authorization header regardless of options, so
     // plumbing one anyway produces a credential path that cannot work.
     authActive: isAuthActive(model),
-    // Whether this API's scheme is genuine HTTP Basic Auth (two credentials,
-    // base64-joined), matching the SDK's own auth.basic signal. Decides
-    // whether the plugin also plumbs a `secret` alongside `apikey` — a
-    // Basic-Auth SDK's own auth stage deletes the header when either is
-    // missing, so a provider forwarding apikey alone could never
-    // authenticate, the same class of gap `apikey`-only forwarding was.
     authBasic: isAuthActive(model) && isHttpBasicAuth(model),
   }
 
@@ -824,8 +502,6 @@ const Main = cmp(function Main(props: any) {
   // target calls its own.
   Gitignore({})
 
-  // Static furniture: LICENSE, CODE_OF_CONDUCT, Makefile, tsfmt.json and
-  // both tsconfigs. Same for every provider.
   Copy({
     from: 'tm/' + target.name,
     replace: { ...ctx$.stdrep },
@@ -843,36 +519,6 @@ const Main = cmp(function Main(props: any) {
 })
 
 
-// HOW THE PROVIDER DEPENDS ON THE SDK IT WRAPS, as one dependency value.
-//
-// Default: the PUBLISHED package pinned to the version the `ts` target
-// publishes, so the two can never disagree. Right whenever the SDK is on a
-// registry — and wrong when it is not. An SDK for a private API, or one not
-// published yet, leaves the provider unable to `npm install` at all: the
-// dependency 404s, so the package cannot be built, tested or released. That
-// is not hypothetical; it is why @seneca/github-provider could not be
-// regenerated and released for weeks.
-//
-// `kind: 'git'` points at a GIT TAG instead, which needs no registry.
-//
-// NPM RESOLVES A GIT DEPENDENCY AGAINST THE REPOSITORY ROOT, and sdkgen
-// generates the TypeScript SDK into `ts/`. So `kind: 'git'` suits an SDK
-// whose package.json IS the repository root, and NOT the layout this
-// toolchain produces.
-//
-// THE `::path:` SUBDIRECTORY SYNTAX DOES NOT WORK, and it looks like it
-// does. npm-package-arg parses `#<ref>::path:ts` and reports
-// `gitSubdir: /ts`, so a spec built that way reads as correct — but the
-// INSTALLER ignores it: npm clones the repository and opens package.json at
-// the clone root, failing with ENOENT on linux, macOS and Windows alike.
-// That was measured, on all three, after the parser had said otherwise.
-//
-// `kind: 'release'` is the form that works for a package in a subdirectory:
-// a GitHub release asset, which is `npm pack` output attached to the tag.
-// npm installs an https tarball natively and never looks at the repository
-// layout at all.
-//
-// `spec` still wins over all of it, for anything the shorthand cannot say.
 function sdkDependency(model: any, target: any, provider: any): string {
   const dep = model?.main?.[KIT]?.target?.[target.name]?.sdk?.dep || {}
 
@@ -913,8 +559,6 @@ function sdkDependency(model: any, target: any, provider: any): string {
   }
 
   if ('release' === kind) {
-    // The asset `npm pack` produces: scope and name flattened, then the
-    // version. `asset` overrides it for a project that names its own.
     const asset = String(dep.asset || '').trim() || (
       provider.sdkPkg.replace(/^@/, '').replace(/\//g, '-') +
       '-' + provider.sdkVersion + '.tgz')
@@ -926,7 +570,6 @@ function sdkDependency(model: any, target: any, provider: any): string {
 }
 
 
-// --- package.json -----------------------------------------------------------
 
 const PackageJson = cmp(function PackageJson(props: any) {
   const { provider, target } = props
@@ -934,19 +577,6 @@ const PackageJson = cmp(function PackageJson(props: any) {
 
   const deps = collectDeps(model, target.name, target.deps, props.ctx$.log)
 
-  // collectDeps returns { name, version, source, raw } — the DECLARED kind
-  // (prod/peer/dev) is on `raw`, not hoisted. Reading `d.kind` instead
-  // silently yields an empty manifest section, which is how the first cut of
-  // this component shipped a package.json with no seneca peers at all.
-  //
-  // `kind` is a COMMA-SEPARATED LIST, so one dependency can land in more than
-  // one manifest section. That is the Seneca plugin convention and not an
-  // embellishment: `seneca` is a PEER (the plugin must run inside the host's
-  // instance, never its own bundled copy) and also a DEV dependency (the test
-  // suite does `require('seneca')` directly, so a bare `npm install` in a
-  // clean checkout has to produce it). collectDeps deduplicates by package
-  // name and the model's dep map is keyed by name, so the same package cannot
-  // be declared twice — the kind has to carry the list instead.
   const dep = (kind: string) => {
     const out: Record<string, string> = {}
     const kinds = (d: any) => String((d.raw && d.raw.kind) || '')
@@ -978,9 +608,6 @@ const PackageJson = cmp(function PackageJson(props: any) {
     keywords: ['seneca', provider.lower, `${provider.lower}-provider`,
       provider.publisher.toLowerCase(), 'sdk'],
     author,
-    // Omitted entirely when the project names none, rather than emitted as an
-    // empty array — npm treats `"contributors": []` as a declaration that
-    // there are none, which is a different claim from not having said.
     ...(0 < contributors.length ? { contributors } : {}),
     license: 'MIT',
     repository: { type: 'git', url: `git+${provider.repoUrl}.git` },
@@ -1012,17 +639,6 @@ const PackageJson = cmp(function PackageJson(props: any) {
         'npm run build && npm run test && npm run repo-tag && ' +
         'npm publish --access public --registry https://registry.npmjs.org',
     },
-    // What actually ships. Without `files`, `npm publish` packs the test
-    // suite and build output into the tarball.
-    //
-    // `doc` IS PART OF THE PACKAGE. The generated README links to
-    // doc/tutorial.md, doc/how-to.md, doc/reference.md and
-    // doc/explanation.md with relative paths, so omitting it published a
-    // README whose every documentation link 404s for anyone reading the
-    // installed package rather than the repository. Either the links become
-    // absolute repository URLs or the files ship; they ship, because the
-    // docs describe the exact version installed and a URL would drift to
-    // whatever main says later.
     files: ['dist', 'doc', 'src/**/*.ts', 'LICENSE'],
     engines: { node: '>=24' },
     dependencies: {
@@ -1042,7 +658,6 @@ const PackageJson = cmp(function PackageJson(props: any) {
 })
 
 
-// --- src/<name>-provider.ts -------------------------------------------------
 
 const ProviderSource = cmp(function ProviderSource(props: any) {
   const { provider } = props
@@ -1212,26 +827,6 @@ function ${provider.pluginName}(this: any, options: ${provider.pluginName}Option
         })
       }
 
-      // Seneca's own entity key is ALWAYS literally `id` — `load$('x')` sets
-      // `q = { id: 'x' }`, and the id of the entity it builds comes off
-      // `data.id`. An API that addresses a record by anything else therefore
-      // needs translating in both directions, or `load$` requests a record
-      // keyed `undefined` and every entity handed back has no id at all — one
-      // that cannot then be saved or removed.
-      // ID TRANSLATION, ONE ALGORITHM AND A TABLE.
-      //
-      // Seneca entities carry exactly one `id`. Plenty of APIs do not: they
-      // key a record by a differently-named field (`repo`, `number`), or by
-      // SEVERAL path parameters at once with no single one that is the id
-      // (github's `/repos/{owner}/{repo}`). Both need translating in both
-      // directions, or `load$` asks for a record keyed `undefined` and every
-      // record handed back has no id to save or remove it by.
-      //
-      // The LOGIC is the same for every API; only which parameters, which
-      // separator and where they live in a response differ, and those are
-      // model data. So this emits one `splitid`, one `joinid` and a table —
-      // not a bespoke pair of functions per entity, which is what it used to
-      // do and which duplicated the same algorithm N times over.
       const translated = provider.entities.filter((e: any) => null != idSpec(e.ent))
 
       if (0 < translated.length) {
@@ -1349,14 +944,6 @@ ${rows}
 `)
       }
 
-      // WHICH SDK OP SERVES EACH `action$`, per entity and per cmd.
-      //
-      // Emitted for EVERY cmd, including the ones with no actions at all.
-      // That empty map is not waste: it is what lets `actionop` refuse an
-      // `action$` on an entity that has none, instead of ignoring the key
-      // and performing an ordinary call. Passing `action$` and getting a
-      // plain save is the failure this whole mechanism exists to prevent —
-      // it is how GitHub's `merge` silently became an "update".
       Content(`  // The custom actions each cmd can reach, as action -> SDK op. An action
   // is an alternative POINT of an ordinary op (\`select.$action\` in the API
   // model), so \`save$\` routes by this map rather than assuming update: an
@@ -1370,12 +957,6 @@ ${rows}
           const name = String(cmd.val$ ?? cmd)
           const map = e.actions[name] || {}
           const names = Object.keys(map).sort()
-          // COMPUTED KEYS, not `jsKey`. An action named `__proto__` written
-          // as a plain (or quoted) object-literal key SETS THE PROTOTYPE
-          // instead of creating a property, so the action would vanish from
-          // its own map and be unreachable. A computed key always defines an
-          // own property. apidef derives an action name from a route segment,
-          // and `__proto__` is a legal one.
           Content(`      ${name}: {${names.map((a: string) =>
             ` [${JSON.stringify(a)}]: '${map[a]}'`).join(',')}${0 < names.length ? ' ' : ''}},
 `)
@@ -1450,8 +1031,6 @@ ${rows}
 
 `)
 
-      // The cmd map, declared up front so every action is attached to a
-      // shape seneca-entity can read before the actions are defined.
       Content(`  const entity: any = {
 `)
       each(provider.entities, (e: any) => {
@@ -1472,22 +1051,7 @@ ${rows}
 `)
 
       each(provider.entities, (e: any) => {
-        // The guard set is PER OP, not the union across the entity's ops. An
-        // entity whose routes are not uniformly nested — a flat `load`, a
-        // nested `create` — used to demand the parent id on the flat call too,
-        // an argument its own SDK request would then never use.
-        //
-        // `save` guards the union of create's and update's keys: one action
-        // serves both and dispatches at runtime, so it cannot know which set
-        // applies until it has the data.
-        // A COMPOSITE-KEY ENTITY GUARDS NOTHING SEPARATELY. Its parent keys
-        // travel INSIDE the id, so demanding `q.owner` as well would reject
-        // `load$('octocat/hello-world')` — the very call the composite id
-        // exists to allow. splitid() does the checking instead, and refuses
-        // a wrong part count by name.
         const eparts = idParts(e.ent)
-        // The whole id description for this entity, or null when none is
-        // needed. `out` branches on it rather than on the record key.
         const espec = idSpec(e.ent)
         const guard = (cmd: string, src: string) => {
           const keys = 'save' === cmd ?
@@ -1501,12 +1065,6 @@ ${rows}
             .join('')
         }
 
-        // THE REFUSAL LINE, for a cmd whose only route addresses a
-        // different resource. Placed AFTER the action branch — an action
-        // route is named explicitly and is exactly how the real operation is
-        // reached — and BEFORE the guards, so the caller is told the cmd
-        // does not exist for this entity rather than being asked for a
-        // parameter that would not have helped.
         const refuse = (cmd: string) => {
           if (true !== (e.idmisaddressed || {})[cmd]) {
             return ''
@@ -1520,26 +1078,8 @@ ${rows}
 `
         }
 
-        // Reading the record's own key off the Seneca query, which always
-        // spells it `id`, and every other required key off its own name.
         const rk = recordKey(e.ent)
 
-        // For a composite key the parameters come out of the split, which the
-        // handler binds to `key` before the call. Any required key the id
-        // does NOT carry still comes off the query.
-        // THE RECORD'S OWN KEY IS ALWAYS SENT, whether or not the match
-        // declares it required.
-        //
-        // An op gathers several routes, and a parameter only one of them
-        // uses comes through OPTIONAL: github's IssueLoadMatch has `owner`
-        // and `repo` required but `id` optional, because the op also covers
-        // `/repos/{owner}/{repo}/issues/comments/{comment_id}`. Sending only
-        // the required keys called `Issue().load({owner, repo})` — the id
-        // the caller passed to `load$` went nowhere, so every read of any
-        // issue in that repo answered with the same record and
-        // `load$('no-such-issue')` returned one. Ten entities failed their
-        // not-found test on it, and the ones that "passed" were passing for
-        // the wrong reason. addressKeys is what the test emitter reads too.
         const sdkArg = (opname: string) => {
           const keys = addressKeys(e.ent, opname)
           if (0 === keys.length) {
@@ -1571,24 +1111,6 @@ ${rows}
           null == espec ? `plain(${expr})` :
             `joinid('${e.name}', plain(${expr})${null == vals ? '' : ', ' + vals})`
 
-        // The action branch, emitted for every cmd whether or not this entity
-        // has actions. `actionop` is what refuses an unknown name, so leaving
-        // it out where the map is empty would restore the silent drop for
-        // exactly the entities most likely to be typed at by mistake.
-        //
-        // IT COMES BEFORE THE PARENT GUARDS, and that ordering is the whole
-        // of its correctness. The guards describe the CANONICAL route —
-        // opParams drops action points when computing them — and an action
-        // route need not be nested the same way: Zoom's canonical update is
-        // `/user/{user_id}/meeting/{id}` while its status action hangs off
-        // `/meeting/{id}`. Guarding first rejected that action for want of a
-        // `user_id` its own URL has no segment for.
-        //
-        // The action path is not left unguarded, it is guarded by the RIGHT
-        // thing: the SDK builds the action's own point and refuses an
-        // unbuildable one with `point_action_invalid`, naming the op and the
-        // action. A call naming no action falls through to the guards exactly
-        // as before.
         const actionBranch = (cmd: string, call: string) => `      const action$ = actionOf(msg)
       if (null != action$) {
         const op$ = actionop(action$, '${e.name}', '${cmd}')
@@ -1630,15 +1152,6 @@ ${actionBranch('load',
           const hasCreate = e.ops.includes('create')
           const hasUpdate = e.ops.includes('update')
 
-          // Dispatch on the SENECA key. The record arriving here is a Seneca
-          // entity's data, so its id lives at `id` whatever the API calls it —
-          // dispatching on the API's key sent every save to `create`, leaving
-          // update unreachable.
-          // A MISADDRESSED UPDATE IS REFUSED, BUT ONLY ON THE UPDATE LEG. A
-          // create needs no record key — the API assigns one — so an entity
-          // whose update route addresses a different resource can still be
-          // created. Dispatch is on `data.id`, so the refusal goes exactly
-          // where the update would have.
           const refuseUpdate = true === (e.idmisaddressed || {}).update ?
             refuse('update') : ''
 
@@ -1654,25 +1167,6 @@ ${actionBranch('load',
               ? `      const res = await sdk.${e.acc}(${entArg}).create(data)`
               : `${refuseUpdate}      const res = await sdk.${e.acc}(${entArg}).update(data)`
 
-          // ... and hand the API back its own key, which Seneca does not know
-          // to send.
-          //
-          // A COMPOSITE KEY IS UNPACKED ONTO THE DATA. The write goes out as
-          // a body plus path parameters, and the SDK reads those parameters
-          // off the same object — so the parts have to be present under
-          // their own names, not fused into `id`. On a create there is no id
-          // yet and the caller supplies the parts directly, which is why this
-          // only runs when an id is there.
-          // THE COMPOSITE SPLIT CANNOT LIVE HERE, before the action branch,
-          // even though that is where the single-key alias sits. The alias
-          // only ever assigns; the split THROWS on an id that is not all its
-          // parts, and an `action$` call is entitled to an id shaped however
-          // that action's own route wants. Running it first turned
-          // `action$: 'no_such_action'` into an id complaint, hiding the
-          // error the caller needed. It is emitted after the action branch
-          // instead — see compositeSave below, spliced where the parent
-          // guards go, which is exactly the position the component already
-          // documents as "after the action branch".
           const compositeSave = 0 < eparts.length ? `
       // Seneca carries this ${e.name}'s key as one \`id\`; the API addresses
       // the record by ${eparts.map((p: string) => '`' + p + '`').join(' and ')}.
@@ -1746,20 +1240,6 @@ ${actionBranch('save',
         }
 
         if (e.cmds.includes('remove')) {
-          // A REMOVE ACTION ANSWERS FOR ITSELF. The canonical remove has
-          // nothing to hand back — the record is gone — so its handler
-          // returns null and takes no `entize`. An action folded into
-          // `remove` is a different endpoint with a response of its own
-          // (`/meeting/{id}/archive` answers with the archive record), and
-          // the other three cmds all pass an action's response through.
-          // Applying the canonical "return null" to it threw that away, so
-          // the action appeared to succeed and yielded nothing.
-          //
-          // `entize` is therefore named, never `_entize`. Naming it
-          // conditionally on the entity HAVING a remove action does not work
-          // and the type-check says so: the action branch is emitted for
-          // every entity — that is what refuses an unknown `action$` on one
-          // with no actions — so the parameter is always referenced.
           Content(`
   ${jsProp('entity', e.name)}.cmd.remove.action =
     async function remove_${e.name}(this: any, entize: any, msg: any) {
@@ -1883,7 +1363,6 @@ if ('undefined' !== typeof module) {
 })
 
 
-// --- src/<Name>Provider-doc.ts ----------------------------------------------
 
 const ProviderDoc = cmp(function ProviderDoc(props: any) {
   const { provider } = props