@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/src/cmp/ocaml/Schema_ocaml.ts

@@ -17,29 +17,6 @@ import {
 } from './utility_ocaml'
 
 
-// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
-//
-// The ocaml peer of src/cmp/ts/Schema_ts.ts. Same two members, same source:
-// optspec from `main.kit.optspec` plus each feature's own `config.options`,
-// entityspec from the entity field sentinels — both built by the shared
-// helpers, so what ocaml validates against and what ts validates against
-// cannot drift.
-//
-// EMBEDDED AS JSON, PARSED AT LOAD, where ts emits an object literal: JSON is
-// a subset of TypeScript's own literal syntax and is not a subset of ocaml's.
-// A string constant read by `Sdk_json.json_read`, exactly as sdk_config.ml
-// carries its data rep above the size threshold.
-//
-// COMPILE ORDER. ocaml links a fixed module list, and sdk_runtime.ml's
-// make_options reads this, so sdk_schema.ml is named in RUNTIME (the
-// Makefile) between sdk_helpers.ml and sdk_runtime.ml. It opens nothing of
-// the SDK beyond Voxgig_struct and Sdk_json, so it cannot close a cycle.
-//
-// The round-trip is exact because the spec holds only strings and booleans:
-// pinned by "strings and booleans only, so the JSON round-trip is lossless"
-// in ts/test/optspec.test.ts. json_read yields `Num (float)` for any number,
-// and struct reads a spec BY EXAMPLE, so one number in here would mean
-// something different in ocaml than in ts.
 const Schema = cmp(async function Schema(props: any) {
   const ctx$ = props.ctx$
   const target = props.target
@@ -54,7 +31,7 @@ const Schema = cmp(async function Schema(props: any) {
     Content(`(* ${model.const.Name} SDK: generated schemas. Do not edit.
  *
  * Built from the model: main.kit.optspec and each feature's config.options
- * for the option spec; entity fields[].type for the entity specs.
+ * for the option spec; entity fields{}.type for the entity specs.
  *
  * opt_spec_value () - the option spec make_options validates client options
  * against. entity_spec_value () - per-entity data and request specs, keyed by

package/project/.sdk/src/cmp/ocaml/SdkError_ocaml.ts

@@ -7,10 +7,6 @@ import {
 } from '@voxgig/sdkgen'
 
 
-// sdk_error.ml — a thin API-facing view of the branded SDK error. The error
-// type and exception themselves live in the runtime (Sdk_types.sdk_error /
-// Sdk_error_exc); this module re-exports them under stable names so callers
-// have a single place to catch/inspect errors (twin of rust core/error.rs).
 const SdkError = cmp(async function SdkError(props: any) {
   const ctx$ = props.ctx$
   const target = props.target

package/project/.sdk/src/cmp/ocaml/TestEntity_ocaml.ts

@@ -74,11 +74,6 @@ let () =
 `)
     }
 
-    // PR review #4: entity e_stream(action, args, callopts) runs the op through
-    // the full pipeline and returns a lazy Seq. Fallback (no streaming feature)
-    // yields the materialised items; with the streaming feature active it yields
-    // from the streaming iterator (chunkSize groups into batches). Needs a list
-    // op with seeded data.
     if (hasList) {
       Content(`
 let () =

package/project/.sdk/src/cmp/ocaml/utility_ocaml.ts

@@ -18,7 +18,6 @@ const OCAML_RESERVED = new Set<string>([
 ])
 
 
-// A collision-free snake_case OCaml (lowercase) identifier for a model name.
 function ocamlVarName(name: string): string {
   let snake = String(name).replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase()
   if ('' === snake || !/^[a-z_]/.test(snake)) {
@@ -28,7 +27,6 @@ function ocamlVarName(name: string): string {
 }
 
 
-// The generated per-entity module basename (module Sdk_entity_<name>).
 function entityModule(name: string): string {
   return 'sdk_entity_' + ocamlVarName(name)
 }
@@ -108,33 +106,8 @@ function formatOcamlValue(val: any, indent: number = 0): string {
 }
 
 
-// Deep-remove meta keys (`foo$`) from a model subtree (twin of go's clean).
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
 const MODEL_META = ['index$', 'key$', 'val$']
 
-// Keys whose value IS the default the runtime already assumes when the key is
-// absent, so emitting them is pure payload.
 const CONFIG_DEFAULT: Record<string, any> = {
   active: true,
   req: false,

package/project/.sdk/src/cmp/perl/Config_perl.ts

@@ -16,24 +16,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// PLUGIN DEFINITION IMPORTS AND THE FEATURE_PLUGINS TABLE (the perl peer
-// of cmp/py/Config_py.ts pluginImports/pluginDefs and cmp/go's
-// featurePlugins).
-//
-// Upstream sekreto replaced its self-registration registry with
-// voxgig/plugin definitions: a provider kind the caller did not pass in
-// via `plugins => [...]` is unknown to that Sekreto. So config imports
-// each active plugin's exported definition BY NAME (the model's
-// `def.perl` map) and hands the list to the feature through
-// FEATURE_PLUGINS.
-//
-// The `def` map is declared in the model rather than derived from
-// filenames because one module may export several definitions (sekreto's
-// Aws.pm exports awssecrets AND awsparams). A def value is the module's
-// path under tm/perl ('feature/secrets/plugins/Voxgig/Sekreto/Plugins/
-// Hashicorp.pm'); the vendored tree keeps upstream's PACKAGE layout, so
-// the module NAME is that path with the vendor root and the extension
-// removed and the separators turned into '::'.
 const PLUGIN_ROOT = 'feature/secrets/plugins/'
 
 
@@ -45,8 +27,6 @@ function pluginModule(path: string): string {
 }
 
 
-// path -> [symbol, ...] for every ACTIVE plugin of every feature, so one
-// `use` line serves a two-definition module.
 function pluginsByPath(feature: any): Record<string, Record<string, string[]>> {
   const out: Record<string, Record<string, string[]>> = {}
 
@@ -54,11 +34,6 @@ function pluginsByPath(feature: any): Record<string, Record<string, string[]>> {
     const bypath: Record<string, string[]> = {}
 
     each(f.plugin, (plugin: any) => {
-      // Filter on `active` HERE rather than trusting the feature object to
-      // arrive filtered: getting it wrong in this direction emits a `use`
-      // for a module the plugin trim just deleted - an SDK that does not
-      // LOAD, rather than one that merely carries too much. Config_py.ts
-      // records the same rule.
       if (false === plugin.active || null == plugin.active) return
 
       for (const [sym, one] of Object.entries(plugin.def?.perl || {})) {
@@ -87,28 +62,8 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  // THE canonical config object, from the shared helper - this component
-  // used to hand-assemble its own (and had already drifted: no server
-  // block, no identity beyond main.name). Passing the target name opts
-  // in to the main slug/version/target identity fields (station
-  // descriptor inputs), matching the ts/js/rb targets.
   const { def: configDef } = configDefinition(model, target.name)
 
-  // `in` and `name` TRAVEL WITH THE PREFIX NOW. apidef resolved both from
-  // the spec's securityScheme all along (joplin's says `in: "query",
-  // name: "token"`) and generation dropped them, so an apiKey-in-query
-  // SDK carried an Authorization header the API does not read. The
-  // placement is a runtime option like the prefix, so it belongs in the
-  // config the SDK loads - see PrepareAuth_perl, which bakes the same two
-  // values into prepare_auth.pm.
-  //
-  // Overlaid HERE rather than inside configDefinition because that helper
-  // is shared by every target, and the other targets' emitters do not
-  // carry the fields yet - widening it would move their output too.
-  //
-  // Emitted ONLY when they differ from the defaults, so a
-  // header/Authorization SDK's config.pm is byte-identical to what it
-  // generated before.
   if (null != configDef.options && null != configDef.options.auth) {
     const authIn = resolveAuthIn(model)
     const authName = resolveAuthName(model)
@@ -124,15 +79,9 @@ const Config = cmp(async function Config(props: any) {
 
   const configJson = JSON.stringify(configDef, null, 2)
 
-  // Gated by the applicability tags, so this target never imports a
-  // plugin definition it has no source for. One rule, one place:
-  // helpers/applicability.
   const bypath = pluginsByPath(targetFeatures(model, target))
   const features = Object.keys(bypath).sort()
 
-  // Every emitted line below is conditional on there being at least one
-  // active plugin definition: an SDK that selected no plugin group (or no
-  // secrets feature at all) gets exactly the config.pm it got before.
   const vendorInc = 0 === features.length ? '' : `
 # The vendored sekreto and plugin ports keep their UPSTREAM package layout,
 # so they resolve through @INC rather than a file-path require - the same
@@ -157,7 +106,6 @@ BEGIN {
         lines.push(`use ${pluginModule(path)} qw(${syms.join(' ')});`)
       }
     }
-    // A module shared by two features is imported once.
     pluginUse = '\n' + Array.from(new Set(lines)).join('\n') + '\n'
 
     const entries = features.map((fname) => {

package/project/.sdk/src/cmp/perl/Entity_perl.ts

@@ -33,7 +33,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/perl/fragment/')
 
-  // Entity files go to entity/ folder
   Folder({ name: 'entity' }, () => {
 
     File({ name: entity.name + '_entity.pm' }, () => {
@@ -56,8 +55,6 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.pm so the class can be renamed independently.
           EntyClass: cls,
 
           // Feature-hook markers. jostraca's built-in `#Name-Tag` pattern is

package/project/.sdk/src/cmp/perl/Main_perl.ts

@@ -57,13 +57,6 @@ const Main = cmp(async function Main(props: any) {
   // Copy tm/perl files with replacements
   Copy({
     from: 'tm/' + target.name,
-    // An ACTIVE feature's INACTIVE plugins do not ship. perl has no
-    // src/feature layout (srcfeature: false), so this blanket copy is the
-    // one place the generate-time plugin trim can act; the model's
-    // `plugin.<group>.path` entries name their files relative to THIS
-    // copy's root ('feature/secrets/plugins/Voxgig/Sekreto/Plugins/
-    // <Kind>.pm'). See helpers/featureSource.pluginExcludes, and
-    // Main_go.ts / Main_py.ts, which do the same.
     exclude: [/src\//, TEST_CONTROL_EXCLUDE, ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
@@ -87,19 +80,6 @@ const Main = cmp(async function Main(props: any) {
               ({ name, indent }: any) =>
                 `${indent}$utility->{feature_hook}->($ctx, "${name}");\n`,
 
-            // SECRETS. The accessor is emitted only when the secrets
-            // feature applies to this target AND the model activates it -
-            // with the feature off the marker line is REMOVED, so the
-            // inactive output is byte-identical to pre-migration.
-            //
-            // The LIVE Sekreto, not a clone: sekreto holds provider and
-            // cache state, so a clone would resolve into a copy nothing
-            // else can see.
-            //
-            // There is deliberately NO resolve seam here. Unlike ts and
-            // py, this port resolves at the TRANSPORT (see
-            // feature/secrets_feature.pm), which every wire path -
-            // entity ops, direct() and graphql() - already crosses.
             '/(?<indent>[ \\t]*)#[ \\t]*#SecretsAccessor[ \\t]*\\n?/':
               ({ indent }: any) => !secrets ? '' :
                 `${indent}# The LIVE Sekreto instance: for arbitrary secrets and redaction.\n` +
@@ -117,7 +97,6 @@ const Main = cmp(async function Main(props: any) {
           }
         },
 
-        // Entities - injected at SLOT
         () => {
           each(entity, (entity: ModelEntity) => {
             const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -128,23 +107,11 @@ const Main = cmp(async function Main(props: any) {
     })
   })
 
-  // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
     Schema({ target })
   })
 
-  // GENERATED, NOT COPIED. Where the credential goes is a fact about the
-  // API, and tm/ can only hold one answer. See PrepareAuth_perl.
-  //
-  // NO FOLDER OPEN HERE, deliberately. perl has no `src/` tree (the ts
-  // port's Main wraps Config and PrepareAuth in `Folder({name:'src'})`,
-  // and this one must not): Main writes `lib/`, `config.pm` and
-  // `features.pm` into the SDK root, and the blanket `Copy({from:
-  // 'tm/perl'})` above lands the utility tree at `<sdk>/utility/`. So
-  // this call sits OUTSIDE the `.` folder above and PrepareAuth opens the
-  // single `utility` folder itself, writing exactly the path the deleted
-  // template occupied.
   PrepareAuth({ target })
 
   // Generate feature factory module

package/project/.sdk/src/cmp/perl/Package_perl.ts

@@ -28,14 +28,6 @@ const Package = cmp(async function Package(props: any) {
   // (e.g. "Voxgig::SDK::Solar" -> dist voxgig-sdk-solar).
   const Name = model.const.Name
 
-  // THE PERL FLOOR IS A FUNCTION OF THE FEATURE SET, not a constant.
-  //
-  // The base SDK is pure 5.018 perl. The secrets feature is not: the
-  // vendored voxgig/plugin runtime it depends on opens with
-  // `use builtin qw(is_bool)`, which is 5.36's and is the only way that
-  // port can tell `true` from `1`. Shipping 5.018 in the manifest of an
-  // SDK that cannot run on 5.018 installs cleanly and then dies at
-  // require time, so the floor moves with the feature.
   const secrets = null != (targetFeatures(model, target) as any).secrets
   const minperl = secrets ? '5.036' : '5.018'
 

package/project/.sdk/src/cmp/perl/PrepareAuth_perl.ts

@@ -16,51 +16,14 @@ import {
 } from './utility_perl'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. The perl peer of cmp/ts/PrepareAuth_ts.ts.
-//
-// This was a static file at `tm/perl/utility/prepare_auth.pm` that opened
-// with `my $HEADER_AUTH = 'authorization';` and never looked further.
-// 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 { model } = props.ctx$
 
-  // `!isAuthSuppressed`, NOT `isAuthActive`. The latter is also false when
-  // the SPEC merely declares no security scheme (`main.kit.info.auth:
-  // false`), and those SDKs still carry a credential: optspec always
-  // declares `apikey` and makeOptions fills `options.auth` from its
-  // defaults, so the runtime guard never fired and they have always sent
-  // it. Only an explicit `main.kit.config.auth.active: false` means "no
-  // credential, ever", which is what isAuthSuppressed reads.
   const active = !isAuthSuppressed(model)
   const where = resolveAuthIn(model)
   const name = resolveAuthName(model)
   const basic = isHttpBasicAuth(model)
 
-  // EXACTLY ONE folder, and it is opened HERE.
-  //
-  // Unlike ts — whose Main opens `Folder({name:'src'})` around Config,
-  // SdkError and this component — perl's Main calls PrepareAuth at the
-  // TOP LEVEL, with no folder open. The template's own path says what the
-  // layout is: `tm/perl/utility/prepare_auth.pm`, copied by Main's
-  // blanket `Copy({from:'tm/perl'})` (which excludes only `src/`), lands
-  // at `<sdk>/utility/prepare_auth.pm`. perl has no `src/` tree at all —
-  // Main writes `lib/`, `config.pm` and `features.pm` straight into the
-  // root. So this component must open `utility` and nothing above it:
-  // opening a second folder would write `src/utility/` or `./utility/`,
-  // a path nothing requires, while the copied file kept being loaded.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.pm' }, () => {
       Content(render({ Name: model.const.Name, active, where, name, basic }))
@@ -78,20 +41,6 @@ type AuthSpec = {
 }
 
 
-// PERL KEEPS ITS HEADER KEYS LOWERCASE, and here that is load-bearing
-// rather than cosmetic. The template's constant was `'authorization'`,
-// and two other generated perl files address that exact spelling:
-// `feature/secrets_feature.pm` rewrites `$headers->{'authorization'}` at
-// the transport seam (it rebuilds the header the way prepare_auth does,
-// so the two must not drift), and `t/pipeline.t` asserts on
-// `$ctx->{spec}{headers}{authorization}`. Emitting the resolved name
-// verbatim would give every default SDK `Authorization` and silently
-// split those three into two different hash keys.
-//
-// Header field names are case-insensitive on the wire (and HTTP/2
-// requires them lowercase), so lowercasing costs nothing and keeps a
-// header-based SDK behaving exactly as it did. A QUERY PARAMETER and a
-// COOKIE name are case-sensitive, and go in verbatim.
 function credName(spec: AuthSpec): string {
   return 'header' === spec.where ? spec.name.toLowerCase() : spec.name
 }
@@ -102,8 +51,6 @@ function render(spec: AuthSpec): string {
 }
 
 
-// NO AUTH AT ALL. A public API's SDK gets a prepare_auth that is honest
-// about it rather than one that deletes a header nobody set.
 function renderInactive(spec: AuthSpec): string {
   return `# ${spec.Name} SDK utility: prepare_auth
 
@@ -206,12 +153,6 @@ const MISSING = `  if (!defined $apikey || Voxgig::Struct::is_none($apikey)
     || (!ref $apikey && ($apikey eq $NOT_FOUND || $apikey eq ''))) {`
 
 
-// Place the credential, or clear what a previous option left behind.
-//
-// Header and query keep the template's if/else, because both have real
-// work to do in both branches. COOKIE HAS NOTHING TO CLEAR (see clear()),
-// and an `if` whose whole body is a comment is not perl anybody writes -
-// so that one returns early and lets the placement run unindented.
 function credBlock(spec: AuthSpec): string {
   if ('cookie' === spec.where) {
     return `
@@ -231,8 +172,6 @@ ${place(spec)}  }
 }
 
 
-// For the cookie placement, where the reason there is no `delete` has to
-// be stated where the delete would have been.
 function noCredNote(spec: AuthSpec): string {
   if ('cookie' !== spec.where) {
     return ''
@@ -245,9 +184,6 @@ function noCredNote(spec: AuthSpec): string {
 }
 
 
-// A one-line reminder, in the generated file, of what the model said —
-// so a reader of a joplin SDK is not left wondering why prepare_auth
-// touches the query string.
 function placementNote(spec: AuthSpec): string {
   if ('query' === spec.where) {
     return `# This API carries its credential as a QUERY PARAMETER (the spec's\n` +
@@ -265,11 +201,6 @@ function placementNote(spec: AuthSpec): string {
 // cookie IS a header.
 function bag(spec: AuthSpec): string {
   if ('query' === spec.where) {
-    // make_spec fills spec.query from prepare_query BEFORE prepare_auth
-    // runs, so the bag is normally already there. A spec handed in
-    // without one still has to receive the credential, and assigning
-    // through an undef lexical would autovivify a hash the spec never
-    // sees - so the bag is created ON THE SPEC.
     return `  my $query = $spec->{query};
   unless (Voxgig::Struct::ismap($query)) {
     $query = {};
@@ -279,9 +210,6 @@ function bag(spec: AuthSpec): string {
 `
   }
 
-  // No blank line after it: this is the template's own line, in the
-  // template's own place, so a header-based SDK's prepare_auth.pm stays
-  // what it was.
   return `  my $headers = $spec->{headers};
 `
 }
@@ -293,15 +221,6 @@ function clear(spec: AuthSpec, ind: string): string {
   }
 
   if ('cookie' === spec.where) {
-    // NOTHING TO CLEAR. The header case deletes its header because the
-    // caller's own `options.headers` may carry a stale `authorization`
-    // that must not go out when auth is suppressed. A cookie is
-    // different: this SDK APPENDS its pair to whatever cookie header the
-    // caller set, and prepare_headers hands it a fresh clone of that
-    // header on every request - so there is never a pair of ours left
-    // behind, and surgically removing one pair from the caller's own
-    // cookie header would be deleting something they put there
-    // deliberately. noCredNote() says so in the generated file.
     return ''
   }
 
@@ -311,9 +230,6 @@ function clear(spec: AuthSpec, ind: string): string {
 
 function place(spec: AuthSpec): string {
   if ('query' === spec.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 `    # 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. make_url

package/project/.sdk/src/cmp/perl/ReadmeEntity_perl.ts

@@ -32,8 +32,6 @@ function perlType(type: any): string {
 }
 
 
-// Operation method spelling for Perl: lowercase methods called on the entity
-// instance, taking a hashref match/data argument.
 const OP_DESC: Record<string, { method: string, desc: string }> = {
   load:   { method: 'load($match)',  desc: 'Load a single entity by match criteria.' },
   list:   { method: 'list()',        desc: 'List entities, optionally matching the given criteria.' },
@@ -64,8 +62,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
-    const fields = entity.fields || []
-    // Model-driven id key: null when this entity has no id-like field.
+    const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
     const eVar = entity.name
 
@@ -110,8 +107,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
       each(fields, (field: any) => {
-        const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${perlType(field.type)}\` | ${desc} |
+        const desc = field.sh || ''
+        Content(`| \`${field.n}\` | \`${perlType(field.t)}\` | ${desc} |
 `)
       })
 

package/project/.sdk/src/cmp/perl/ReadmeExamplesTest_perl.ts

@@ -8,33 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits t/readme_examples.t — a Test::More COMPLETENESS GATE that guarantees
-// every fenced `perl` code example across the package docs is unit-tested. It
-// reads ALL THREE docs — the root (multi-language) ../README.md, the
-// Perl-specific ../README.md, and ../REFERENCE.md — extracts every fenced perl
-// block (tagged by source doc + index) and enforces:
-//
-//   1. SYNTAX  — `perl -c` on every block (with the SDK lib on @INC, so a
-//      construction block's `use <Name>SDK` is actually compiled/loaded).
-//   2. RUN     — every RUNNABLE block (one that constructs the SDK, drives
-//      `$client`, or performs an entity op) is EXECUTED offline in seeded
-//      test mode against the real SDK. The captured stdout+stderr is scanned
-//      for FATAL perl-level programming-error markers REGARDLESS of exit code,
-//      so a bug an example's own eval swallows and prints is still caught.
-//      A domain not-found / 404 error never matches FATAL, so it is tolerated.
-//   3. COMPLETENESS — every block is partitioned into exactly one of
-//      {executed, syntaxchecked-nonrunnable, illustration}; the counts must
-//      sum to the total. A runnable-looking block that was not executed lands
-//      in neither bucket and FAILS the gate.
-//
-// A runnable block is rewritten so its client is a test-mode client
-// (<Name>SDK->test) seeded with an in-memory fixture for every entity it
-// references; any real ->new/->test constructor is rewritten. A block that
-// only uses `$client` (constructed in an earlier fenced block) gets a test
-// client prepended.
-//
-// The emitted Perl builds the ``` fence via chr(96) so this generator string
-// contains no backticks of its own.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target, ctx$: { model } } = props
 

package/project/.sdk/src/cmp/perl/ReadmeModel_perl.ts

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

package/project/.sdk/src/cmp/perl/ReadmeRef_perl.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -64,7 +64,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -173,7 +173,7 @@ Prepare a fetch definition without sending. Returns the \`fetchdef\` and dies on
     // Entity reference sections
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
-      const fields = ent.fields || []
+      const fields = Object.values(ent.fields || {})
       // Model-driven id key: null when this entity has no id-like field.
       const idF = entityIdField(ent)
       const eVar = ent.name
@@ -206,9 +206,9 @@ my $${eVar} = $client->${ent.Name};
 | --- | --- | --- | --- |
 `)
         each(fields, (field: any) => {
-          const req = field.req ? 'Yes' : 'No'
-          const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${perlType(field.type)}\` | ${req} | ${desc} |
+          const req = field.r ? 'Yes' : 'No'
+          const desc = field.sh || ''
+          Content(`| \`${field.n}\` | \`${perlType(field.t)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -233,7 +233,7 @@ my $${eVar} = $client->${ent.Name};
               if (fop.active === false) return '-'
               return 'Yes'
             })
-            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+            Content(`| \`${field.n}\` | ${cols.join(' | ')} |
 `)
           })
 
@@ -387,9 +387,6 @@ my $client = ${model.const.Name}SDK->new({
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }
 

package/project/.sdk/src/cmp/perl/ReadmeTopQuick_perl.ts

@@ -46,8 +46,6 @@ my $client = ${ctor};
     const eName = nom(exampleEntity, 'Name')
     const eVar = eName.toLowerCase()
     const opnames = Object.keys(exampleEntity.op || {})
-    // Model-driven id key: null when the entity has no id-like field, in which
-    // case the load example takes no match argument.
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {

package/project/.sdk/src/cmp/perl/Schema_perl.ts

@@ -12,24 +12,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
-//
-// The perl peer of src/cmp/ts/Schema_ts.ts. Same two members, same source:
-// optspec from `main.kit.optspec` plus each feature's own `config.options`,
-// entityspec from the entity field sentinels — both built by the shared
-// helpers, so what perl validates against and what ts validates against
-// cannot drift.
-//
-// EMBEDDED AS JSON, PARSED AT LOAD, in a heredoc, exactly as config.pm
-// carries its config — and here the parse is not merely convenient, it is the
-// point. Perl has no native boolean scalar, so a spec written as a perl
-// literal has to name Voxgig::Struct::JTRUE/JFALSE by hand at every boolean
-// slot (the hand-written optspec this replaces did); parse_json produces
-// those singletons itself, which is what `$BOOLEAN` matches against.
-//
-// The round-trip is exact because the spec holds only strings and booleans:
-// pinned by "strings and booleans only, so the JSON round-trip is lossless"
-// in ts/test/optspec.test.ts.
 const Schema = cmp(async function Schema(props: any) {
   const ctx$ = props.ctx$
   const target = props.target
@@ -46,7 +28,7 @@ const Schema = cmp(async function Schema(props: any) {
     Content(`# ${model.const.Name} SDK: generated schemas. Do not edit.
 #
 # Built from the model: \`main.kit.optspec\` and each feature's
-# \`config.options\` for the option spec; entity \`fields[].type\` for the
+# \`config.options\` for the option spec; entity \`fields{}.type\` for the
 # entity specs.
 
 use strict;