@voxgig/sdkgen 4.20.0 → 4.22.0

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

@@ -23,6 +23,7 @@ import {
 
 import { Package } from './Package_perl'
 import { Config } from './Config_perl'
+import { Schema } from './Schema_perl'
 import { PrepareAuth } from './PrepareAuth_perl'
 import { Gitignore } from './Gitignore_perl'
 import { MainEntity } from './MainEntity_perl'
@@ -56,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,
@@ -86,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` +
@@ -116,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}`)
@@ -127,22 +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.' },
@@ -65,7 +63,6 @@ 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 idF = entityIdField(entity)
     const eVar = entity.name
 

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/ReadmeExplanation_perl.ts

@@ -20,6 +20,7 @@ is a hashref.
 ${target.name}/
 ├── lib/${model.const.Name}SDK.pm    -- Main SDK module (package ${model.const.Name}SDK)
 ├── config.pm                    -- Configuration
+├── schema.pm                    -- Generated option + entity specs
 ├── features.pm                  -- Feature factory
 ├── core/                        -- Core types and context
 ├── entity/                      -- Entity implementations

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)
 
@@ -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

@@ -0,0 +1,89 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  // Beside config.pm, and for the same reason: the generated data sits at the
+  // SDK root, so nothing under utility/ or feature/ has to reach up for it.
+  File({ name: 'schema.pm' }, () => {
+
+    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.
+
+use strict;
+use warnings;
+
+use File::Basename ();
+use Cwd ();
+
+my $__dir;
+BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
+require(Cwd::abs_path("$__dir/lib/Voxgig/Struct.pm"));
+
+package ${model.const.Name}Schema;
+
+my $OPTSPEC_JSON = <<'END_OPTSPEC_JSON';
+${JSON.stringify(optspec, null, 2)}
+END_OPTSPEC_JSON
+
+my $ENTITYSPEC_JSON = <<'END_ENTITYSPEC_JSON';
+${JSON.stringify(entityspec, null, 2)}
+END_ENTITYSPEC_JSON
+
+sub make_optspec {
+  return Voxgig::Struct::parse_json($OPTSPEC_JSON);
+}
+
+sub make_entityspec {
+  return Voxgig::Struct::parse_json($ENTITYSPEC_JSON);
+}
+
+# SHARED SPECS, the shape ${model.const.Name}Config::shared_config uses and for
+# the same reasons: the spec is read on every client construction and never
+# mutated, so a per-call parse would be pure waste.
+#
+# The returned structures are SHARED: treat them as read-only. make_options
+# validates AGAINST the spec and writes into the options, never into the spec.
+my $SHARED_OPTSPEC;
+my $SHARED_ENTITYSPEC;
+
+sub optspec {
+  $SHARED_OPTSPEC = make_optspec() unless defined $SHARED_OPTSPEC;
+  return $SHARED_OPTSPEC;
+}
+
+sub entityspec {
+  $SHARED_ENTITYSPEC = make_entityspec() unless defined $SHARED_ENTITYSPEC;
+  return $SHARED_ENTITYSPEC;
+}
+
+1;
+`)
+  })
+})
+
+
+export {
+  Schema
+}

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

@@ -270,8 +270,6 @@ ${listSkipBlock}  my $client = $setup->{client};
     }
 
     if (hasLoad && loadPoint) {
-      // Skip live direct-load only when we can't fill path params:
-      // no spec examples and no list-bootstrap. Spec examples win first.
       const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
         ? `  if ($setup->{live}) {
     note('live direct-load needs real ID - set *_ENTID env var with real IDs to run');

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

@@ -12,34 +12,8 @@ function projectPath(suffix?: string): string {
 }
 
 
-// Strip model-internal keys (ending in `$`) so generated config JSON only
-// carries API-shaped data.
-// 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,