@voxgig/sdkgen 4.21.0 → 4.23.0

package/src/cmp/Registered.ts

@@ -1,33 +1,3 @@
-// `registerComponent` — add a per-target component of your own.
-//
-// WHY THIS EXISTS
-//
-// Every built-in resolves its per-language half by convention:
-// `Main` loads `cmp/<target>/Main_<target>`, `Test` loads
-// `cmp/<target>/Test_<target>`, and `ReadmeTop` loads
-// `cmp/<target>/ReadmeTopQuick_<target>` with `{ ignore: true }` so a target
-// that has not implemented it is simply skipped.
-//
-// A PROJECT had no way into that mechanism. voxgig-solardemo-sdk wanted a
-// per-target `AGENTS.md` and had to hand-wire the dispatch in its own
-// `Root.ts`:
-//
-//   if ('ts' === target.name) { AgentsTs({ target }) }
-//   else if ('go' === target.name) { AgentsGo({ target }) }
-//
-// which duplicates the internal dispatch, does not scale past a couple of
-// targets, and — because the branches live inline in Root.ts — is exactly
-// what stops a project's root wiring from being resynced with the scaffold.
-//
-// With this, the same thing is one line and target-agnostic:
-//
-//   const Agents = registerComponent('Agents')
-//   ...
-//   Agents({ target })
-//
-// resolving `cmp/<target>/Agents_<target>` and doing nothing for a target
-// that has no such file. `doctor` reports those files as ADDITIVE — the
-// project's own work — rather than as drift.
 
 import { cmp } from 'jostraca'
 

package/src/cmp/Security.ts

@@ -3,8 +3,6 @@ import { cmp, Content, File } from 'jostraca'
 import { SECURITY_EMAIL, apiName, repoInfo } from '../helpers/packageMeta'
 
 
-// Root SECURITY.md: a responsible-disclosure policy pointing at the Voxgig
-// security contact, with the generated / unofficial disclosure inline.
 const Security = cmp(function Security(props: any) {
   const { ctx$ } = props
   const { model } = ctx$

package/src/cmp/Test.ts

@@ -8,6 +8,8 @@ import { requirePath } from '../utility'
 import { ensureStdrep } from '../helpers/stdrep'
 
 
+import { liveHint } from '../helpers/resolved'
+
 import {
   KIT,
   getModelPath
@@ -21,11 +23,11 @@ const Test = cmp(function Test(props: any) {
 
   const points = Object.values(model.main.kit.entity || {}).flatMap((entity: any) =>
     Object.values(entity.op || {}).flatMap((op: any) => op.points || [])) as any[]
-  if (points.some(point => point.contract && JSON.parse(point.contract.json).live)) {
+  if (points.some(point => liveHint(point))) {
     const supported = ['ts', 'js'].includes(target.name)
     File({ name: 'live-coverage.json' }, () => Content(JSON.stringify({
       version: 1, target: target.name, scenarios: supported ? 'supported' : 'unsupported',
-      points: points.map(point => point.contract?.id || point.method + ' ' + point.orig),
+      points: points.map(point => point.co?.id || point.m + ' ' + point.o),
       ...(!supported ? { reason: 'This target does not yet execute declarative live recipes. Its existing tests do not establish full operation coverage.' } : {}),
     }, null, 2)))
     if (!supported) log.warn({ point: 'live-scenarios-unsupported', note: 'Declarative live recipes are not executed by target ' + target.name })

package/src/cmp/TestControl.ts

@@ -17,31 +17,6 @@ const TEST_CONTROL_FILE = 'sdk-test-control.json'
 const TEST_CONTROL_EXCLUDE = new RegExp('(^|/)' + TEST_CONTROL_FILE + '$')
 
 
-// `sdk-test-control.json` is the ONE generated file a project is meant to edit
-// by hand: it names the tests to skip, the live pacing, and the extra client
-// options a live run needs (`test.client.options`).
-//
-// It shipped as part of each target's blanket `Copy({ from: 'tm/<lang>' })`,
-// and a Copy has no per-file "leave it alone if it already exists" — so every
-// `npm run generate` overwrote whatever the project had put there. The
-// documented workaround, editing the template master under `.sdk/tm/`, is
-// worse: `doctor` reports it as drift and the next `target add <lang>` reverts
-// it.
-//
-// So it is emitted HERE instead, write-once: `File({ exclude: true })` returns
-// early when the file already exists (FileOp), which is exactly the semantics
-// the file is documented to have. A project without one yet gets the
-// template's default; a project that has edited one keeps its edits across
-// both `generate` and `target add`.
-//
-// The content still comes from the target's own template, so there remains
-// exactly one copy of the default on disk.
-//
-// The template is addressed the SAME way the Copy this replaces addressed it:
-// `tm/<lang>/...` relative to the working directory, which is the project's
-// `.sdk`. Resolved to absolute here because Fragment resolves a RELATIVE
-// `from` against the OUTPUT folder instead — a different base, and the one
-// place these two could silently disagree.
 const TestControl = cmp(function TestControl(props: {
   target: { name: string }
   dir: string

package/src/helpers/applicability.ts

@@ -1,37 +1,7 @@
-// Which features a target can actually take.
-//
-// THE ONE PLACE THIS RULE LIVES. `Feature` (what source is copied), the
-// per-language `Config_<lang>` and `Main_<lang>` components (what the
-// generated registry, imports and metadata contain) and `configDefinition`
-// (the embedded config) must all reach the same answer for one
-// (feature, target) pair. They previously each read the raw feature map,
-// which is how a feature with no source for a target still reached that
-// target's imports.
-//
-// The shape is `docs/design/feature-tags.md`: a feature declares what it
-// NEEDS, a target declares what it PROVIDES, and the feature applies when
-// `needs` is a subset of `provides`. Both default to empty, so a feature
-// that needs nothing applies everywhere — every feature that existed
-// before this gate keeps its behaviour with no model edit, which is what
-// makes the change additive.
-//
-// A named target list was the cheaper design and fails on time: it has to
-// be edited for targets the feature's author has never heard of, so a
-// published package starves every target added after its release. A tag is
-// a claim about the feature that stays true as the target set grows.
 
 import { KIT, getModelPath } from '@voxgig/apidef'
 
 
-// Tags are a MAP keyed by tag name, `{ sekreto: true }` — see the schema
-// note on `needs`. A map because aontu unifies maps by key, so a package
-// can add one tag without restating the others; and because a defaulted
-// list disjunction in this position hangs the unifier on a real project's
-// model. A tag counts only when its value is true, so a tag can be turned
-// off by overriding it rather than by deleting the key.
-//
-// A list is still accepted, for a hand-written model that used the shape
-// docs/design/feature-tags.md first proposed.
 function tags(val: any): string[] {
   if (Array.isArray(val)) {
     return val.filter((t: any) => 'string' === typeof t)
@@ -49,8 +19,6 @@ function tags(val: any): string[] {
 function featureApplies(feature: any, target: any): boolean {
   const needs = tags(feature && feature.needs)
 
-  // The common case, and the reason this is additive: no needs, applies
-  // anywhere. Checked first so a target with no `provides` is unaffected.
   if (0 === needs.length) {
     return true
   }
@@ -61,12 +29,6 @@ function featureApplies(feature: any, target: any): boolean {
 }
 
 
-// The features that apply to `target`, in the same map shape
-// `getModelPath(model, 'main.<kit>.feature')` returns — already
-// active-filtered by getModelPath, then gated by the tags.
-//
-// `target` may be the target object or its name; components hold the
-// object, `configDefinition` is only given the name.
 function targetFeatures(model: any, target: any): Record<string, any> {
   const feature = getModelPath(model, `main.${KIT}.feature`, { required: false }) || {}
 
@@ -80,10 +42,6 @@ function targetFeatures(model: any, target: any): Record<string, any> {
     return feature
   }
 
-  // Keyed off the map, not off `f.name`: the key is what every consumer
-  // indexes by, and rebuilding from a field would drop an entry whose
-  // model never set one. Order is not preserved on purpose — consumers
-  // re-sort with `each`, which is what keeps output byte-stable.
   const applies: Record<string, any> = {}
   for (const [name, f] of Object.entries(feature as Record<string, any>)) {
     if (featureApplies(f, t)) {
@@ -95,28 +53,10 @@ function targetFeatures(model: any, target: any): Record<string, any> {
 }
 
 
-// THE CLOSED VOCABULARY. The schema comment says applicability tags are a
-// closed set; without this, `provides: &: boolean` accepts any key, so a
-// typo (`sekrreto`) compiles cleanly and silently makes the feature apply
-// NOWHERE — the worst failure shape, because the feature simply vanishes
-// with no diagnostic.
-//
-// Extended by adding a tag here AND documenting it in model/sdkgen.aon.
 const TAGS = [
   // A vendored sekreto port lives in this target's feature container.
   'sekreto',
 
-  // The target can VALIDATE against the generated `Schema` module: the
-  // model's option spec and, when a feature asks for them, per-entity
-  // struct.validate specs.
-  //
-  // NOT "emits Schema". Every target emits one — make_options reads the
-  // option spec out of it — so that claim is universal and gates nothing.
-  // This tag is the `validate` FEATURE's `needs`, and a feature
-  // also needs its per-target source: tagging a target that has no
-  // `tm/<lang>/src/feature/validate/` makes the feature apply with nothing
-  // to copy. featuremodel.test.ts holds the two together in both
-  // directions.
   'schema',
 ]
 

package/src/helpers/buildIdNames.ts

@@ -1,15 +1,3 @@
-// Build the list of placeholder ID names that the test setup populates into
-// `setup.idmap`. The set is the union of:
-//   - the entity's own ids (`<entity>01..03`)
-//   - every ancestor entity's ids (`<anc>01..03`)
-//   - every literal string value referenced by `step.match` across the flow
-//     (e.g. path-parameter aliases like `year01` for `/{year}/domain` — apidef
-//     doesn't always populate `relations.ancestors` when the parent in the
-//     path is a bare parameter rather than an entity, so we have to mine the
-//     flow steps directly to avoid KeyError-ing the idmap from generated test
-//     code)
-//
-// Identical helper was previously inlined in TestEntity_{go,py,lua,rb,php}.ts.
 
 const COUNT = 3 // 3 ids per name: <name>01, <name>02, <name>03
 
@@ -38,24 +26,24 @@ function buildIdNames(entity: EntityLike, flow: FlowLike): string[] {
 
   const ancestors: string[] = (entity.relations?.ancestors || []).flat()
   for (const anc of ancestors) {
-    for (let i = 1; i <= COUNT; i++) push(`${anc}0${i}`)
+    for (let i = 1; i <= COUNT; i++) push(`${entityRelationName(anc)}0${i}`)
   }
 
   const steps = Array.isArray(flow?.step)
     ? flow.step
     : Object.values(flow?.step || {})
-  for (const step of steps) {
-    if (step?.match) {
-      for (const v of Object.values(step.match)) {
+  for (const step of steps.filter((s: any) => false !== s.a)) {
+    if (step?.m) {
+      for (const v of Object.values(step.m)) {
         if (typeof v === 'string' && v && !v.endsWith('$')) push(v)
       }
     }
-    // step.data values can also be aliased via setup (e.g. update step.data
+    // step.d values can also be aliased via setup (e.g. update step.d
     // = {data_type_id: 'data_type01'} → setup adds idmap[data_type_id] =
     // idmap[data_type01]). The right-hand side `data_type01` must be in the
     // idmap or the alias resolves to undefined.
-    if (step?.data) {
-      for (const v of Object.values(step.data)) {
+    if (step?.d) {
+      for (const v of Object.values(step.d)) {
         if (typeof v === 'string' && v && !v.endsWith('$')) push(v)
       }
     }
@@ -65,6 +53,16 @@ function buildIdNames(entity: EntityLike, flow: FlowLike): string[] {
 }
 
 
+function entityRelationName(ref: string): string {
+  return ref.startsWith('$.main.kit.entity.') ? ref.slice('$.main.kit.entity.'.length) : ref
+}
+
+function flowSteps(flow: FlowLike): any[] {
+  return Object.values(flow?.step || {}).filter((step: any) => false !== step.a)
+}
+
 export {
   buildIdNames,
+  entityRelationName,
+  flowSteps,
 }

package/src/helpers/canonSpec.ts

@@ -1,42 +1,3 @@
-// Canonical type-sentinel -> struct.validate SPEC mapper.
-//
-// The sibling of canonType: that table turns a field's canon sentinel into a
-// language TYPE NAME (what the generated source declares); this one turns the
-// same sentinel into a struct.validate SPEC VALUE (what the generated runtime
-// checks a payload against). One vocabulary, two renderings, and — as with
-// canonType — a SINGLE mapping that components must not copy locally.
-//
-// WHY THIS IS ALMOST NOTHING. apidef stores `$STRING`, `$INTEGER`, `$NUMBER`,
-// `$BOOLEAN`, `$NULL`, `$ARRAY`, `$OBJECT`, `$ANY` on `fields[].type`, and
-// struct.validate's own vocabulary is `$STRING $NUMBER $INTEGER $DECIMAL
-// $BOOLEAN $NULL $NIL $MAP $LIST $FUNCTION $INSTANCE $ANY $CHILD $ONE $EXACT`.
-// Six of the eight scalar names are the IDENTICAL string. Only three things
-// have to be adapted, and each is a real difference rather than a translation:
-//
-//   1. CONTAINERS ARE NAMED DIFFERENTLY. apidef speaks OpenAPI ($ARRAY,
-//      $OBJECT), struct speaks its own value model ($LIST, $MAP).
-//
-//   2. UNIONS ARE SHAPED DIFFERENTLY. apidef nests the members —
-//      ['`$ONE`', [a, b]] — and struct wants them flat: ['`$ONE`', a, b].
-//      The nested form does not fail loudly, which is the trap: struct reads
-//      the inner LIST as a single alternative, so `['`$ONE`', ['`$STRING`',
-//      '`$INTEGER`']]` rejects the string 'x' with "expected [string,integer]".
-//
-//   3. STRUCT'S `$STRING` REJECTS THE EMPTY STRING. That is right for an
-//      option (an empty apikey is a missing apikey) and wrong for API data,
-//      where '' is an ordinary value a server returns. A field spec therefore
-//      widens to ['`$ONE`', '`$STRING`', ['`$EXACT`', '']].
-//
-// OPTIONALITY. struct requires every key its spec names, so an optional field
-// is the union of its type with `$NIL` (which matches an ABSENT value; `$NULL`
-// matches a stored JSON null). `req: false` on a field, and `optional: true`
-// on an opRequestShape item, both land here.
-//
-// WHAT THIS CANNOT EXPRESS, because the model does not carry it (the same
-// KNOWN GAPS canonType records): array ELEMENT types, nested object schemas,
-// enums, string formats, and any numeric or length bound. A spec built here
-// checks the shape the model knows about and nothing more — which is why
-// record specs are `$OPEN` (below) rather than closed.
 
 import { each } from 'jostraca'
 
@@ -63,16 +24,12 @@ const S_NULL = sentinel('NULL')
 const S_OPEN = sentinel('OPEN')
 
 
-// Canon sentinel key -> the struct.validate sentinel that checks it.
-// STRING is deliberately absent: it needs the empty-string widening above and
-// is handled in canonToSpec, so a caller cannot get the bare form by accident.
 const CANON_STRUCT: Record<string, string> = {
   INTEGER: sentinel('INTEGER'),
   NUMBER: sentinel('NUMBER'),
   BOOLEAN: sentinel('BOOLEAN'),
   NULL: sentinel('NULL'),
 
-  // The container renaming (difference 1 above).
   ARRAY: sentinel('LIST'),
   OBJECT: sentinel('MAP'),
 
@@ -80,7 +37,6 @@ const CANON_STRUCT: Record<string, string> = {
 }
 
 
-// A string that may be empty (difference 3 above).
 const SPEC_STRING: any[] = [S_ONE, S_STRING, [S_EXACT, '']]
 
 
@@ -94,16 +50,7 @@ function alternatives(spec: any): any[] {
 }
 
 
-// A spec that also admits an ABSENT value.
-//
-// struct requires every key its spec names, so this is how "optional" is
-// spelled. Flattened through `alternatives`, so widening something that is
-// already a union (an empty-string-tolerant `$STRING`, an apidef `$ONE`)
-// adds one member rather than nesting a union inside a union — which struct
-// reads as a single alternative and rejects.
 function optionalSpec(spec: any): any {
-  // `$ANY` already admits an absent value, so widening it would only make
-  // the spec longer and its error messages worse.
   if (S_ANY === spec) {
     return spec
   }
@@ -112,14 +59,6 @@ function optionalSpec(spec: any): any {
 }
 
 
-// Map one field/param type sentinel to a struct.validate spec value.
-//
-// Unknown or missing sentinel -> `$ANY`, never a throw: this mirrors
-// canonToType's contract, and for the same reason. A sentinel this table has
-// not met is a model the generator should still emit for, and an over-strict
-// spec would reject live traffic at runtime rather than fail a build.
-//
-// `optional` widens the result with `$NIL` so an absent key passes.
 function canonToSpec(type: unknown, optional?: boolean): any {
   let spec: any
 
@@ -136,27 +75,6 @@ function canonToSpec(type: unknown, optional?: boolean): any {
         }
       }
 
-      // A NULLABLE FIELD NEEDS `$NIL`, NOT JUST `$NULL`.
-      //
-      // apidef writes a nullable field as ['`$ONE`', [<type>, '`$NULL`']],
-      // and `$NULL` on its own does match a stored null. Inside a union it
-      // does not: struct resolves each alternative through a lookup that
-      // reads a stored null as "no value", so the value that reaches the
-      // `$NULL` validator is undefined and every nullable field rejected the
-      // one value it exists to allow. `$NIL` matches that no-value, so the
-      // pair covers both readings.
-      //
-      // THE COST, stated because it is real and not an oversight: `$NIL` is
-      // also how an OPTIONAL field is spelled, and struct cannot tell a
-      // stored null from an absent key inside a union — the lookup collapses
-      // them before any alternative sees the value. So a REQUIRED nullable
-      // field (`string | null`, `req: true`) also passes when the key is
-      // missing. The alternative is worse: drop `$NIL` and a nullable field
-      // rejects null, which is the one value it is declared to hold, for
-      // EVERY such field rather than weakening presence on a subset. Closing
-      // the gap needs a presence check outside struct, i.e. a second
-      // validation mechanism beside the one this whole module exists to
-      // reuse. Revisit if struct gains a spelling that separates them.
       if (0 <= members.indexOf(S_NULL) && members.indexOf(S_NIL) < 0) {
         members.push(S_NIL)
       }
@@ -178,35 +96,21 @@ function canonToSpec(type: unknown, optional?: boolean): any {
 }
 
 
-// The spec for one entity RECORD: every active field, keyed by name.
-//
-// OPEN, ALWAYS. apidef records the properties a spec declared, which is not a
-// promise that a response carries nothing else — a server that adds a field is
-// not breaking its clients, and a closed spec would turn that into a client
-// error for every caller at once. The declared fields are type-checked; the
-// rest pass. A caller who wants the closed reading drops `$OPEN` at runtime
-// (the validate feature's `strict` option does exactly that).
 function entityDataSpec(ent: any): Record<string, any> {
   const spec: Record<string, any> = { [S_OPEN]: true }
 
   const fields = (ent && ent.fields) ? each(ent.fields) : []
   for (const f of fields) {
-    if (null == f || null == f.name || false === f.active) {
+    if (null == f || null == f.n || false === f.a) {
       continue
     }
-    spec[f.name] = canonToSpec(f.type, false === f.req)
+    spec[f.n] = canonToSpec(f.t, false === f.r)
   }
 
   return spec
 }
 
 
-// The spec for one operation's REQUEST payload.
-//
-// The members and their optionality are opRequestShape's answer, not a second
-// reading of the model: the partiality policy that decides what a generated
-// `<Name>CreateData` requires is the same policy that decides what a create
-// call must carry, and two copies of it would drift the moment one is edited.
 function entityOpSpec(ent: any, opname: string): Record<string, any> | null {
   const { items } = opRequestShape(ent, opname)
   if (0 === items.length) {
@@ -241,24 +145,6 @@ function entitySpecs(ent: any): { data: Record<string, any>, op: Record<string,
 }
 
 
-// A DEFAULT VALUE, read as a type.
-//
-// A feature declares its options as defaults (`ttl: 5000`, `currency: 'USD'`,
-// `methods: ['GET']`) — a map written to document what happens when you say
-// nothing, not to state a type. struct.validate reads it by example, and by
-// example is SHARPER than the author meant: `unit: 0` says "an integer", so
-// cost's own `unit: 0.002` failed its own feature's spec; `header: ''` says
-// "a non-empty string", which the default itself is not.
-//
-// So the default is kept for its KIND and widened to that kind's sentinel.
-// Nothing is lost by dropping the value: a feature's defaults are applied by
-// the feature's own code (`this._options.currency || 'USD'`), never by this
-// spec — each feature entry is optional, and struct fills in nothing through
-// an optional union.
-//
-// This applies to a DEFAULTS map only. `main.kit.optspec` is written as a
-// spec, so its concrete values are the author's own choice of constraint and
-// are passed through untouched.
 function byExampleSpec(val: any): any {
   if (null == val) {
     return S_ANY

package/src/helpers/canonType.ts

@@ -1,36 +1,3 @@
-// Canonical type-sentinel -> language primitive type mapper.
-//
-// SOURCE OF TRUTH for the sentinel set: @voxgig/apidef (`VALID_CANON` +
-// `CANON_ONE`, exported from the package). VALID_CANON maps an OpenAPI type
-// NAME -> a `$SENTINEL` string (e.g. 'string' -> `$STRING`). The model stores
-// those sentinels on every `fields[].type` and op `points[].args.params[].type`.
-// A multi-type (OpenAPI `type: [a, b]`) is stored as the ARRAY-shaped union
-// sentinel `['`$ONE`', [member, ...]]` (see canonToType below).
-//
-// This table maps the SENTINEL the other way -> a concrete primitive type in
-// each target language, so the typed-model generators (EntityTypes_<lang>.ts)
-// and the README type columns (ReadmeRef_<lang>.ts / ReadmeEntity_<lang>.ts)
-// can turn the model's field/param sentinels into real language types. It is
-// the SINGLE mapping per language: components must not keep local copies.
-//
-// Kept as a small mirror here (rather than importing VALID_CANON at runtime)
-// because apidef is a peer dependency and the table is the INVERSE direction.
-//
-// `ts/test/canonsync.test.ts` guards it two ways: the vocabulary and every
-// language column are pinned LOCALLY (that check always runs), and the table
-// is cross-checked against apidef's exported VALID_CANON/CANON_ONE when the
-// installed apidef exports them. Note that the currently published apidef
-// (6.3.1) does NOT export them, so the cross-check skips — do not rely on it
-// alone; add a new sentinel to the local list in the same change.
-//
-// KNOWN GAPS (papered over sanely, documented for the port):
-//  - Unknown / missing sentinel  -> the language's "any" (never throws).
-//  - Array element typing is not in the model: $ARRAY maps to an untyped
-//    list/array. `list` ops return T[] via op-kind inference in the op
-//    fragment, NOT via a field sentinel.
-//  - Object/nested field schemas are not in the corpus: $OBJECT maps to the
-//    language's open record/map type.
-//  - No enum/format/nullability beyond the `req` flag.
 
 // Target languages sdkgen supports (go-cli / go-mcp reuse 'go'). The targets
 // with a fully dynamic value model (clojure, haskell, ocaml, perl, zig) have
@@ -41,15 +8,6 @@ type CanonLang =
   | 'csharp' | 'java' | 'kotlin' | 'scala' | 'swift' | 'dart'
   | 'rust' | 'c' | 'cpp' | 'elixir'
 
-// Bare sentinel key (backticks + leading `$` stripped, upper-cased)
-// -> per-language primitive type name.
-//
-// Column notes:
-//  - kotlin: every type is nullable (`?`) — the kotlin emitter drops
-//    per-member optionality because the column is already-nullable.
-//  - java/scala: boxed JVM types (nullable), so optionality needs no marker.
-//  - rust/c/cpp/swift: `Value`/`voxgig_value*`/`VMap` are the vendored
-//    dynamic value types those runtimes ship.
 const CANON_TYPE: Record<string, Record<CanonLang, string>> = {
   STRING: {
     ts: 'string', js: 'string', py: 'str', php: 'string', rb: 'String',
@@ -114,11 +72,6 @@ const CANON_ANY: Record<CanonLang, string> = {
   rust: 'Value', c: 'voxgig_value*', cpp: 'Value', elixir: 'any()',
 }
 
-// Union ($ONE) member separator for languages with a native union/sum type
-// syntax. Languages absent here have no way to express an anonymous union in
-// a type position, so a $ONE sentinel degrades to that language's "any".
-// (php 8 unions exist but cannot combine with the `?` optional prefix the
-// emitters use, so php deliberately degrades to `mixed`.)
 const CANON_UNION_JOIN: Partial<Record<CanonLang, string>> = {
   ts: ' | ',
   js: '|',
@@ -128,23 +81,6 @@ const CANON_UNION_JOIN: Partial<Record<CanonLang, string>> = {
 }
 
 
-// Canonical sentinel -> pandas dtype, for the `py-data` target's generated
-// DataFrame accessors. Deliberately NOT a CanonLang column: py-data is a
-// consumer target layered on `py`, not a language, and these are storage
-// dtypes rather than type-annotation names.
-//
-// NULLABLE dtypes throughout ('Int64' not 'int64', 'boolean' not 'bool').
-// The model carries no nullability beyond the `req` flag, and API payloads
-// omit optional fields freely, so a column that looks integral in one page
-// can arrive with nulls in the next. NumPy's int64/bool cannot hold NA and
-// would silently upcast to float64/object mid-fetch, changing a column's
-// dtype based on which rows came back — the pandas nullable extension types
-// keep it stable.
-//
-// There is no $DATE / $DATETIME sentinel in apidef's vocabulary (the model
-// carries no string formats), so date handling is NOT inferred here. It is
-// an explicit runtime opt-in via the accessor's `parse_dates=` kwarg. Do not
-// add a DATE row unless apidef starts emitting the sentinel.
 const PANDAS_DTYPE: Record<string, string> = {
   STRING: 'string',
   INTEGER: 'Int64',
@@ -182,21 +118,6 @@ function canonKey(sentinel: unknown): string {
 }
 
 
-// The bare key of the sentinel a VALUE of this type must satisfy, resolving
-// the union sentinel `['`$ONE`', [member, ...]]` to its first non-NULL member
-// (recursively — a member may itself be a union).
-//
-// canonKey alone cannot do this: given an array it stringifies it, so a
-// nullable `['`$ONE`', ['`$NUMBER`','`$NULL`']]` field yields neither NUMBER
-// nor anything else recognizable and every caller falls through to its
-// "unknown, use a string" branch. canonToType meanwhile renders that same
-// sentinel as `number | null`, so the doc example said `'..._id'` while the
-// generated type said `number` — a TS2322 in the SDK's own README, which is
-// exactly the disagreement the example helpers exist to prevent.
-//
-// A union of nothing but NULL resolves to NULL; an unrecognized array shape,
-// or an empty member list, resolves to '' (unknown) like any missing
-// sentinel.
 function canonScalarKey(sentinel: unknown): string {
   if (Array.isArray(sentinel)) {
     if ('ONE' !== canonKey(sentinel[0]) || !Array.isArray(sentinel[1])) {
@@ -219,14 +140,6 @@ function canonScalarKey(sentinel: unknown): string {
 }
 
 
-// Map a field/param type sentinel to a target-language primitive type.
-// Unknown or missing sentinel -> that language's "any" (never throws).
-//
-// The union sentinel `['`$ONE`', [member, ...]]` (apidef CANON_ONE, produced
-// for OpenAPI multi-types) renders as a joined member union in languages with
-// union syntax (see CANON_UNION_JOIN); elsewhere it degrades to "any".
-// Members may themselves be unions (handled recursively) or the literal
-// 'Any' apidef emits for an unknown member name (canonKey maps it to ANY).
 function canonToType(sentinel: unknown, lang: string): string {
   const l = lang as CanonLang
   const fallback = CANON_ANY[l] ?? 'any'

package/src/helpers/collectDeps.ts

@@ -1,24 +1,3 @@
-// Collect target-language dependencies from features and from the target's
-// own `deps` block, applying the active-flag semantics that every Package_*.ts
-// template was hand-rolling identically:
-//
-//   - feature deps  : included when `dep.active === true`  (default off)
-//   - plugin  deps  : the same, and only for an ACTIVE plugin of that feature
-//   - target  deps  : included when `dep.active !== false` (default on)
-//
-// THE PLUGIN LEVEL IS GATED ONE STEP DEEPER THAN THE FEATURE. A feature's
-// deps flow as soon as the feature is active; a plugin is a trimmable part
-// within an active feature, so a dependency only its files use must not
-// reach the manifest until that plugin is active too. rust's mini vault is
-// the case: it takes `ring` for AES-256-GCM, and at feature level that
-// would land in every secrets-enabled rust SDK, including the ones whose
-// chain is `[env, dotenv]` and which never compile a vault.
-//
-// The two sources are kept distinct via the `source` field so callers can
-// apply their own version defaults / formatting (e.g. go uses `v0.0.0`,
-// python `0.0`). The original dep object is exposed as `raw` for callers that
-// need extra fields like `dep.replace` (go module replace directives) or
-// `dep.kind` (prod/dev/peer).
 
 import { targetFeatures } from './applicability'
 
@@ -45,12 +24,6 @@ function collectDeps(
   // dependency into its generated manifest.
   const feature = targetFeatures(model, targetName)
 
-  // Deduplicate by package name. Two features can require the same package
-  // (or a feature and the target itself can), and every Package_<lang>.ts
-  // renders one manifest line per entry — a duplicate key is a hard parse
-  // error in go.mod and Cargo.toml, and silently last-wins in package.json.
-  // FIRST occurrence wins, so the deterministic (sorted-key) feature order
-  // decides; a conflicting version is reported rather than silently dropped.
   const seen: Record<string, DepEntry> = {}
 
   const add = (dep: any, source: 'feature' | 'target', owner: string) => {

package/src/helpers/definition.ts

@@ -1,18 +1,3 @@
-// WHERE A KIND'S DEFINITION FILES LIVE.
-//
-// `model/<kind>/<name>.aon`, with `model/<kind>/<kind>-index.aon` as the
-// include list beside them. One line of path-building — and it was written out
-// longhand in three places (the resolver, the feature catalogue, doctor), each
-// with its own idea of which files in that directory count.
-//
-// That is the same shape of defect this workstream has now fixed four times:
-// the same rule expressed twice, drifting. The manifest makes it four callers,
-// so it becomes one function first.
-//
-// The EXCLUSIONS matter as much as the path. A `model/<kind>/` directory holds
-// the index file (a list of includes, not a definition) and, in the shipped
-// scaffold, a `README.md`. Neither is an item, and a caller that forgets one
-// invents a `feature-index` feature.
 
 import Path from 'node:path'
 
@@ -37,24 +22,10 @@ function indexName(kind: string): string {
 }
 
 
-// Every item of `kind` a `.sdk` folder DEFINES, sorted. Sorted because it
-// feeds an exact-set comparison against a manifest and, through
-// `availableFeatures`, the feature-trim catalogue — both of which are compared
-// as text, so a readdir order that varies by filesystem would vary the result.
-//
-// An absent directory is not an error: a package providing only features has
-// no `model/target/`, and that is the normal shape of a feature package.
 function definitionNames(fs: any, sdkfolder: string, kind: string): string[] {
   const dir = definitionFolder(sdkfolder, kind)
   const index = indexName(kind)
 
-  // `existsSync` is true for a REGULAR FILE and for a directory this process
-  // cannot read, so guarding on it and then calling `readdirSync` let a bare
-  // `ENOTDIR`/`EACCES` escape to callers that have no catch — including
-  // `featureCatalogue`, which runs on every ordinary `target add`, so the
-  // whole add aborted with an errno instead of a diagnostic. Not-a-readable-
-  // directory is the same answer as not-there: this kind defines nothing
-  // here.
   let entries: string[]
   try {
     entries = fs.readdirSync(dir)