@voxgig/sdkgen 4.20.0 → 4.22.0

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

@@ -21,6 +21,7 @@ import {
 
 import { Package } from './Package_ocaml'
 import { Config, secretsBuild } from './Config_ocaml'
+import { Schema } from './Schema_ocaml'
 import { Gitignore } from './Gitignore_ocaml'
 import { MainEntity } from './MainEntity_ocaml'
 import { SdkError } from './SdkError_ocaml'
@@ -28,16 +29,6 @@ import { PrepareAuth } from './PrepareAuth_ocaml'
 import { entityModule, ocamlString } from './utility_ocaml'
 
 
-// Features whose source is a CONTAINER under the top-level feature/ dir,
-// beside the single template module (sdk_features.ml) every other ocaml
-// feature lives in. Today that is `secrets`: feature/secrets_feature.ml,
-// feature/secrets/ (the vendored @voxgig/sekreto port, the voxgig/plugin
-// host and the provider kinds - some forty modules of key-store,
-// request-signing and child-process code that an SDK which never asked for
-// secrets must not ship) and its shipped suite under test/feature/secrets/.
-// Anything named here is EXCLUDED from the verbatim copy unless the model
-// SELECTS the feature (see the Copy below). The lua and clojure targets gate
-// their containers the same way (Main_lua.ts, Main_clojure.ts).
 const CONTAINED = ['secrets']
 
 
@@ -51,16 +42,6 @@ const Main = cmp(async function Main(props: any) {
   // it has no source for. One rule, one place: helpers/applicability.
   const feature = targetFeatures(model, target)
 
-  // THE feature/<name>/ CONTAINER IS GATED HERE, at generate time - the
-  // top-level-container peer of the `srcFeatureExcludes` gate ts and js
-  // apply to src/feature/<name>/. `target add` keeps an unselected
-  // feature out of a project's tm/ in the first place (ocaml.aon has
-  // `feature: { trim: true }`); this covers a feature switched off after
-  // it was added, and the generator suite, which copies the whole scaffold
-  // tree. An inactive feature's vendored kind files go with it - every
-  // declared group's, not only the groups marked inactive, because
-  // pluginExcludes below walks only ACTIVE features (Main_c's
-  // inactivePluginExcludes, for the same reason one target over).
   const containerExcludes = CONTAINED
     .filter((name: string) => null == (feature as any)[name])
     .flatMap((name: string) => [
@@ -73,22 +54,6 @@ const Main = cmp(async function Main(props: any) {
 
   Gitignore({})
 
-  // Copy tm/ocaml verbatim with ProjectName replacement. The src/ subtree
-  // only stages per-feature custom-source dirs (srcfeature: false, so unused),
-  // excluded like the go/rust targets. Stray compiled artifacts and built
-  // test binaries are excluded defensively. test/vendor/omni (the vendored
-  // @voxgig/omni corpus engine) rides along verbatim - the replacements are
-  // ProjectName-shaped and the port names nothing project-specific, so it
-  // lands byte-identical to its recorded vendored.json digest.
-  //
-  // pluginExcludes: the generate-time plugin trim (an ACTIVE feature's
-  // INACTIVE plugin group's declared files stay out of the tree). The
-  // model's ocaml `path` entries are target-root-relative, which is this
-  // Copy's root - helpers/featureSource documents that getting the root
-  // wrong makes the trim a silent no-op. ocaml has `srcfeature: false`, so
-  // the per-feature Copy in cmp/Feature.ts - where pluginExcludesFor
-  // normally applies this trim - never runs for it, and this whole-tree
-  // Copy is the ONLY copy the target has (Main_go.ts precedent).
   Copy({
     from: 'tm/' + target.name,
     exclude: [/src\//, /\.(cmi|cmo|cmx|cma|cmxa|o|a)$/, /a\.out$/,
@@ -99,26 +64,6 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // THE BUILD SEAM: feature/secrets/feature.mk, GENERATED only when the
-  // model activates `secrets` for this target. It is what only the model
-  // knows and only a Makefile can say in OCaml - the module list in
-  // DEPENDENCY ORDER (ocamlc compiles a module before anything that uses
-  // it and has no link-time reordering, so a wildcard over the vendored
-  // directories would not build), the -I paths, unix.cma for the dotenv
-  // and file built-ins, the gated suite, and, ONLY when an active plugin
-  // group declares `needs.fetch`, the OpenSSL binding: plugins/tls_stubs.c
-  // compiled and linked with `-custom -cclib -lssl -cclib -lcrypto`. The
-  // template Makefile includes `$(wildcard feature/*/feature.mk)` - it names
-  // no feature itself - and every variable a fragment sets is empty without
-  // one, so an SDK without secrets - or with the built-in
-  // chain alone, or with `secretspec` alone - runs no C compiler and links
-  // no OpenSSL. The shape lua's native.mk and c's kinds.c take.
-  //
-  // The vendored stub opens with the vendoring tool's three-line `(* *)`
-  // provenance header (every file under tm/ocaml is stamped in ocaml's
-  // comment syntax; the guard holds that), which a C compiler cannot
-  // read - so the rule feeds the compiler from line four, as lua's does.
-  // Compiler line numbers are therefore three lower than in the file.
   const build = secretsBuild(model, target)
   if (null != build) {
     Folder({ name: 'feature' }, () => {
@@ -153,25 +98,37 @@ FEATURE_SRC = $(SECRETS_PLUGIN) $(SECRETS_CORE) $(SECRETS_HELPERS) $(SECRETS_KIN
 FEATURE_TESTS = test/feature/secrets/t_secrets.ml
 `)
 
-          if (build.tls) {
+          const objs = [
+            ...(build.tls ? ['feature/secrets/plugins/tls_stubs.o'] : []),
+            ...build.stubs.map((one) => one.replace(/\.c$/, '.o')),
+          ]
+          const libs = [
+            ...(build.tls ? ['-cclib', '-lssl'] : []),
+            ...(build.tls || 0 < build.stubs.length ? ['-cclib', '-lcrypto'] : []),
+          ]
+
+          if (0 < objs.length) {
             Content(`
-# THE ONE EXTERNAL DEPENDENCY, behind the plugin groups that need a
-# transport (${build.tlsGroups.join(', ')}): plugins/tls.ml's externals live in
-# plugins/tls_stubs.c against OpenSSL, so the stub is compiled here and the
-# bytecode executables are linked \`-custom\` with libssl and libcrypto.
-# The stub is fed from line four (past the provenance header, see above).
+# THE C OBJECTS THIS CHAIN NEEDS${build.tls ? `, and the one external
+# dependency behind the plugin groups that need a transport
+# (${build.tlsGroups.join(', ')}): plugins/tls.ml's externals live in
+# plugins/tls_stubs.c against OpenSSL` : ''}${0 < build.stubs.length ? `${build.tls ? '. ' : `,
+# behind `}the mini vault's own stub (${build.stubGroups.join(', ')}), whose
+# AES-256-GCM and PBKDF2 come from libcrypto` : ''}. Each stub is compiled
+# here and the bytecode executables are linked \`-custom\`, and each is fed
+# to the compiler from line four (past the provenance header, see above).
 OCAMLLIB = $(shell $(OCAMLC) -where)
-FEATURE_OBJ = feature/secrets/plugins/tls_stubs.o
-FEATURE_LINK = -custom -cclib -lssl -cclib -lcrypto
-
-feature/secrets/plugins/tls_stubs.o: feature/secrets/plugins/tls_stubs.c
-	@command -v $(CC) >/dev/null 2>&1 || { echo "secrets: a C compiler ($(CC)) is needed to build the OpenSSL binding that this SDK's secrets plugin kinds (${build.tlsGroups.join(', ')}) run - install one, or use only the built-in provider kinds" >&2; exit 1; }
+FEATURE_OBJ = ${objs.join(' ')}
+FEATURE_LINK = -custom ${libs.join(' ')}
+${objs.map((obj) => `
+${obj}: ${obj.replace(/\.o$/, '.c')}
+	@command -v $(CC) >/dev/null 2>&1 || { echo "secrets: a C compiler ($(CC)) is needed to build the C stub that this SDK's secrets plugin kinds (${build.groups.join(', ')}) run - install one, or use only the built-in provider kinds" >&2; exit 1; }
 	tail -n +4 $< | $(CC) -std=c11 -O2 -Wall -Wextra -I$(OCAMLLIB) -x c - -c -o $@
-`)
+`).join('')}`)
           }
           else {
             Content(`
-# No active plugin group needs a transport, so the OpenSSL binding is not
+# No active plugin group needs a transport or a C stub, so nothing is
 # compiled and nothing is linked beyond the OCaml distribution.
 FEATURE_OBJ =
 FEATURE_LINK =
@@ -182,29 +139,16 @@ FEATURE_LINK =
     })
   }
 
-  // Generated API config + branded-error re-export.
+  Schema({ target })
   Config({ target })
   SdkError({ target })
 
   // sdk_prepare_auth.ml is GENERATED, not templated: WHERE the credential
   // goes (header / query / cookie, and under what name) is a fact about the
-  // API, and tm/ can only hold one answer. ocaml had no prepare_auth
-  // template to replace - the body was a `let` inside the monolithic
-  // tm/ocaml/sdk_runtime.ml - so this is a real extraction: the module
-  // keeps the `prepare_auth_util` name by aliasing this one, and every
   // existing caller (the utility record, make_spec, the secrets feature's
   // re-run, the shipped suites) resolves unchanged. See PrepareAuth_ocaml.
-  //
-  // AT ROOT LEVEL, with no Folder open. The ocaml tree is flat at the
-  // target root and the Makefile's `RUNTIME` names `sdk_prepare_auth.ml`
-  // by that exact path, between sdk_helpers.ml (which it uses) and
-  // sdk_runtime.ml (which uses it) - ocamlc compiles in the order it is
-  // handed and has no link-time reordering. Emitting it inside a Folder
-  // would put it where neither `RUNTIME` nor `-I .` looks, and
-  // sdk_runtime.ml would fail with `Unbound module Sdk_prepare_auth`.
   PrepareAuth({ target })
 
-  // sdk_client.ml — the client constructors, direct/prepare, and the
   // per-entity accessors (twin of the go root package + rust core/sdk.rs).
   File({ name: 'sdk_client.' + target.ext }, () => {
 
@@ -264,7 +208,6 @@ let prepare (client : sdk_client) (fetchargs : value) : value =
     // rather than naming a generated accessor - the shipped feature suites
     // are templates and know no project's entity names - has no way to reach
     // one without this. The go peer is the untyped interface go-cli/go-mcp
-    // dispatch through. None for a name this SDK did not generate.
     const names = each(entity).map((e: ModelEntity) => e.name).sort()
     if (0 === names.length) {
       Content(`

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

@@ -12,19 +12,6 @@ import { packageName } from './utility_ocaml'
 import { secretsBuild } from './Config_ocaml'
 
 
-// <name>.opam — opam package metadata (publish is declared pending in the
-// model; the build itself is stock ocamlc via the Makefile and needs no opam
-// packages). Twin of rust Cargo.toml, but the runtime is dependency-free so
-// there is no depends list beyond the OCaml compiler.
-//
-// The secrets feature's build model is NOT emitted from here, unlike
-// Package_rust's rustls dependency table: the Makefile reads the generated
-// feature/secrets/feature.mk (Main_ocaml), which lists the vendored modules
-// in dependency order and turns the OpenSSL binding on only when a plugin
-// group needing a transport is active. What this manifest CAN state is the
-// system dependency that binding introduces - `depexts`, opam's word for a
-// distribution package - and it states it on exactly the same condition,
-// read from the same helper, so the two cannot drift.
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
   const target = props.target

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

@@ -21,68 +21,20 @@ import {
 } from './utility_ocaml'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. The ocaml peer of PrepareAuth_ts / PrepareAuth_py;
-// read PrepareAuth_ts first, it carries the full account of the defect.
-//
-// 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, so the SDK sent a header the API does not
-// read and never sent the query parameter it does. Four repos in the cedar
-// fleet ship SDKs that cannot authenticate for this reason: joplin
-// (`token`), pipedrive (`api_token`), trello (`key`), lm-umbrella
-// (`apiKey`).
-//
-// OCAML IS THE ODD ONE OUT: it had no prepare_auth TEMPLATE to replace.
-// The body was one `let` inside tm/ocaml/sdk_runtime.ml, the 1200-line
-// module that holds every `*_util` and the registrar that binds them. So
-// the extraction is a real one, and the shape was chosen rather than
-// inherited - see EXTRACTION SHAPE below.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
   const where = resolveAuthIn(model)
 
-  // A HEADER NAME IS LOWER-CASED HERE; A QUERY OR COOKIE NAME IS NOT.
-  // apidef writes `name: "Authorization"`, the extracted body hardcoded
-  // `"authorization"`, and the whole ocaml runtime keys headers in lower
-  // case: make_spec writes "content-type", header_ci lower-cases before it
-  // looks up, the secrets feature rewrites `headers.authorization`, and the
-  // SHARED corpus asserts `ctx:spec:headers:authorization` - which
-  // test/primary_utility_test.ml drives through this very function. A
-  // struct map key is case-SENSITIVE, so emitting "Authorization" verbatim
-  // would put the credential under a key nothing in the SDK reads.
-  //
-  // A query parameter and a cookie name are case-sensitive ON THE WIRE:
-  // lm-umbrella's `apiKey` is not `apikey`, and lower-casing it would break
-  // exactly the APIs this change exists to fix. So they keep the spec's
-  // spelling, byte for byte.
   const resolved = resolveAuthName(model)
   const name = 'header' === where ? resolved.toLowerCase() : resolved
 
-  // Read so the resolution is visible at generation time, even though the
-  // emitted code takes the prefix from options at runtime (the secrets
-  // feature rewrites it there, and `auth.prefix` is a documented option).
   const prefix = resolveAuthPrefix(model)
 
   const basic = isHttpBasicAuth(model)
   const active = authSwitchedOn(model)
 
-  // FOLDER NESTING. Main_ocaml calls this with NO Folder open: its own
-  // Config, SdkError and `sdk_client.ml` all write straight to the target
-  // root, and the only Folder it opens (`feature/secrets` for feature.mk)
-  // is scoped to that one block and closed before this call. The ocaml tree
-  // is FLAT at the root - sdk_types.ml, sdk_helpers.ml, sdk_runtime.ml,
-  // sdk_features.ml, sdk_config.ml all sit there, and the Makefile names
-  // each by that exact path in `RUNTIME`.
-  //
-  // So this component opens NO folder. Opening one (`utility`, say, copying
-  // the c and lua ports) would write `<root>/utility/sdk_prepare_auth.ml`,
-  // which is NOT what `RUNTIME` lists and NOT where `-I .` looks: ocamlc
-  // would report `Unbound module Sdk_prepare_auth` while compiling
-  // sdk_runtime.ml, and `utility/` already holds the vendored struct port,
-  // which the Copy owns.
   File({ name: 'sdk_prepare_auth.' + target.ext }, () => {
     Content(render({
       project: model.const.Name, active, where, name, prefix, basic,
@@ -91,30 +43,6 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
 })
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING (the py port found
-// this first; six of the eleven ports found it independently).
-//
-// `isAuthActive` is false whenever the SPEC declares no security scheme
-// (`main.kit.info.auth: false`). That is a statement about the DEFINITION,
-// not a ban on ever sending a credential: apidef writes it for every spec
-// with no securitySchemes block - GitHub's official OpenAPI included - and
-// those SDKs are still expected to honour an `apikey` the caller passes.
-// `optspec` always declares `apikey`, and make_options fills `options.auth`
-// from the optspec defaults, so the runtime `auth = Noval | Null` guard
-// never fired and every such SDK has ALWAYS sent the credential.
-//
-// Gating the body on `isAuthActive` therefore does not trim dead code, it
-// deletes working authentication - and takes the secrets feature with it,
-// since that resolves a secret into `options.apikey` and prepare_auth then
-// places nothing. generatedcompile's own fixture is one of these
-// (`main: kit: info: { ... auth: false }` in generateharness), and the
-// shipped tm/ocaml/test/feature/secrets/t_secrets.ml drives a LIVE client
-// on it.
-//
-// `main.kit.config.auth.active: false` is the project saying "this SDK
-// sends no credential, ever" - an explicit per-SDK switch nobody sets by
-// accident, and the only signal that can honestly be honoured before
-// runtime. So it is the only one used here.
 function authSwitchedOn(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -132,42 +60,6 @@ type AuthSpec = {
 }
 
 
-// EXTRACTION SHAPE: ITS OWN COMPILATION UNIT, and the module keeps calling
-// it.
-//
-// The preferred shape, and it fits: `sdk_prepare_auth.ml` is module
-// `Sdk_prepare_auth`, compiled between sdk_helpers.ml and sdk_runtime.ml -
-// the Makefile's `RUNTIME` is an explicit ORDERED list (ocamlc compiles a
-// module before anything that uses it and has no link-time reordering), so
-// the position is stated there rather than discovered.
-//
-// THE BINDING IS PRESERVED EXACTLY. sdk_runtime.ml keeps
-//
-//   let prepare_auth_util = Sdk_prepare_auth.prepare_auth_util
-//
-// so every existing call site resolves at the same name it always did:
-//   - `u_prepare_auth = prepare_auth_util` in new_utility, and
-//     `u.u_prepare_auth <- prepare_auth_util` in register - the closure
-//     record that IS the ocaml registrar (sdk_types.ml declares the field);
-//   - `u.u_prepare_auth ctx` in make_spec_util (sdk_runtime.ml) and in the
-//     secrets feature's re-run of the pipeline (sdk_features.ml);
-//   - `prepare_auth_util c` in test/primary_utility_test.ml, which reaches
-//     it through `open Sdk_runtime` and drives the SHARED corpus section
-//     through it - the parity suite requires ocaml to execute `prepareAuth`
-//     (parity.test.ts FULL tier), so that name had to keep resolving;
-//   - `cl.cl_utility.u_prepare_auth ctx` in the four t_pipeline.ml cases.
-// Nothing in the tree was re-pointed at the new module, and nothing needed
-// to be.
-//
-// THE ONE THING THAT HAD TO MOVE. The body reads the client's options
-// through `client_options_map`, which was defined in sdk_runtime.ml - i.e.
-// AFTER this module in compile order, so it could not be called from here.
-// It is a one-line accessor over `sdk_client.cl_options` with no dependency
-// on anything else in that module, so it moved DOWN into sdk_helpers.ml,
-// where `cc`, `cu`, `getp` and every other shared accessor already live.
-// sdk_runtime.ml opens Sdk_helpers, so its own three call sites are
-// unchanged. The alternative - re-deriving the options map here - would
-// fork a definition that must not drift.
 function render(spec: AuthSpec): string {
   const head = `(* ${spec.project} SDK utility: prepare_auth.
  *
@@ -234,20 +126,6 @@ function placement(spec: AuthSpec): string {
 }
 
 
-// HEADER. Behaviourally what sdk_runtime.ml's `prepare_auth_util` did, line
-// for line and idiom for idiom: the same `auth_no_spec` error, the same
-// `__NOTFOUND__` sentinel read through `getprop ~alt`, the same
-// missing-credential handling (delete the header), the same empty-prefix
-// rule. Only the credential NAME moves with the model - and it resolves to
-// "authorization" for every header SDK, so those regenerate unchanged.
-//
-// The HTTP Basic block is the one addition, and it is emitted ONLY when the
-// model says the scheme IS basic (`isHttpBasicAuth`). An ordinary
-// bearer/apiKey SDK carries no dead code and no behaviour change. ocaml's
-// extracted body never had this branch: a basic scheme resolved
-// `auth.prefix` to "Basic" and sent `Basic <apikey>` - a single token where
-// the scheme demands `base64(user:pass)`, which cannot authenticate. The
-// other eleven ports added the same branch for the same reason.
 function renderHeader(spec: AuthSpec, head: string): string {
   return head + `
 let option_apikey = "apikey"
@@ -318,12 +196,6 @@ let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
 }
 
 
-// COOKIE. A cookie IS a header, so the credential rides the header bag -
-// but the \`cookie\` header is SHARED with whatever cookies the caller set
-// through options.headers, so our pair is SPLICED in and out rather than
-// the header assigned over. Splicing also makes this idempotent: the
-// secrets feature re-runs the pipeline on a retried request, and an
-// assignment would leave the credential in the header twice.
 function renderCookie(spec: AuthSpec, head: string): string {
   return head + `
 let cookie_header = "cookie"
@@ -382,17 +254,6 @@ let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
 }
 
 
-// True HTTP Basic Auth: TWO credentials, base64-joined. Emitted only for a
-// HEADER placement, because the scheme IS a header -
-// \`Authorization: Basic base64(user:pass)\` cannot be expressed as a query
-// parameter or a cookie pair, so renderQuery and renderCookie never carry
-// it.
-//
-// It is the FIRST of three `unit` branches - basic, no-credential,
-// single-token - and the shared \`(Some spec, None)\` after them is the one
-// result. Written that way rather than as an early return because OCaml
-// sequences with \`;\`: a branch returning the tuple could not sit beside
-// two returning unit.
 const BASIC = `       if (match getpath_s options "auth.basic" with Bool b -> b | _ -> false) then begin
          (* True HTTP Basic Auth needs TWO credentials, base64-joined - a
           * single token in the header (the branch below) can never
@@ -417,12 +278,6 @@ const BASIC = `       if (match getpath_s options "auth.basic" with Bool b -> b
 `
 
 
-// OCaml's stdlib has no base64 (4.14 ships none, and the SDK is
-// dependency-free: stock ocamlc, no opam, no dune). The vendored sekreto
-// port has one, but it lives inside the OPTIONAL secrets feature - an SDK
-// that never asked for secrets does not compile it - so an HTTP Basic SDK
-// carries its own. Emitted only in that branch, so nothing else pays for
-// it. The lua port carries the same encoder for the same reason.
 const BASE64 = `
 let b64_alphabet =
   "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"

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

@@ -2,23 +2,6 @@
 import { cmp, Content, File } from '@voxgig/sdkgen'
 
 
-// Emits test/readme_examples_test.ml — a structural gate over every ```ocaml
-// fenced block in the three docs that ship ocaml examples:
-//   - the root README.md (top-level, multi-language quick start)
-//   - the per-language ocaml/README.md
-//   - the per-language ocaml/REFERENCE.md
-//
-// DESIGN NOTE (mirrors ReadmeExamplesTest_rust): the py gate shells out to a
-// python subprocess to COMPILE + EXECUTE every block. A faithful ocaml port
-// would shell out to `ocamlc` against each extracted snippet — a large,
-// environment-sensitive harness that cannot be authored safely without a build
-// to validate it (and the generated SDK ships a dependency-free stock-ocamlc
-// build, no doc-test tooling). This gate instead validates that every
-// documented ocaml block is PRESENT and STRUCTURALLY well-formed (balanced
-// delimiters, non-empty). It is a real, always-passing test that keeps the docs
-// honest about block structure; upgrading it to a true compile gate (a temp
-// project that `ocamlc`s each block against the generated SDK) is a follow-up.
-// Missing docs are tolerated (a run may generate a subset of phases).
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target, ctx$: { model } } = props
 

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

@@ -22,6 +22,7 @@ Build request maps with the \`jo\` / \`ja\` helpers and read fields back with
 ${target.name}/
 ├── sdk_client.ml               -- Main SDK client (constructors + accessors)
 ├── sdk_config.ml               -- Embedded API config + feature factory
+├── sdk_schema.ml               -- Generated option + entity specs
 ├── sdk_error.ml                -- Branded error re-exports
 ├── sdk_entity_*.ml             -- Per-entity implementations (one each)
 ├── sdk_types.ml                -- Core pipeline types

package/project/.sdk/src/cmp/ocaml/ReadmeRef_ocaml.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 {
@@ -69,7 +69,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)
 
@@ -392,9 +392,6 @@ let client = Sdk_client.make (jo [
 \`\`\`
 
 `)
-      // 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/ocaml/Schema_ocaml.ts

@@ -0,0 +1,76 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  ocamlString,
+} from './utility_ocaml'
+
+
+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) || {}
+
+  File({ name: 'sdk_schema.' + target.ext }, () => {
+
+    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.
+ *
+ * opt_spec_value () - the option spec make_options validates client options
+ * against. entity_spec_value () - per-entity data and request specs, keyed by
+ * entity name. Both parse once and memoise: the spec is read on every client
+ * construction and never mutated, so a per-call parse would be pure waste.
+ *
+ * The returned values are SHARED: treat them as read-only. make_options
+ * validates AGAINST the spec and writes into the options, never into it. *)
+
+open Voxgig_struct
+
+let optspec_data = "${ocamlString(JSON.stringify(optspec))}"
+
+let entityspec_data = "${ocamlString(JSON.stringify(entityspec))}"
+
+let optspec_memo : value option ref = ref None
+
+let entityspec_memo : value option ref = ref None
+
+let opt_spec_value () : value =
+  match !optspec_memo with
+  | Some v -> v
+  | None ->
+    let v = Sdk_json.json_read optspec_data in
+    optspec_memo := Some v;
+    v
+
+let entity_spec_value () : value =
+  match !entityspec_memo with
+  | Some v -> v
+  | None ->
+    let v = Sdk_json.json_read entityspec_data in
+    entityspec_memo := Some v;
+    v
+`)
+  })
+})
+
+
+export {
+  Schema
+}

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,