@voxgig/sdkgen 4.20.0 → 4.22.0

package/project/.sdk/src/cmp/zig/Main_zig.ts

@@ -21,48 +21,18 @@ import {
 
 
 import { Config, FeaturePlugins, BUILTIN_FEATURES } from './Config_zig'
+import { Schema } from './Schema_zig'
 import { Gitignore } from './Gitignore_zig'
 import { MainEntity } from './MainEntity_zig'
 import { Package } from './Package_zig'
 import { PrepareAuth } from './PrepareAuth_zig'
 
 
-// Which features ship a zig test suite under test/feature/<name>/, and the
-// file build.zig must NAME to run it. zig has no test auto-discovery: a
-// suite the build file does not list exists and never runs. A map rather
-// than a convention because the file has to EXIST - `zig build` fails the
-// whole build on a test path it cannot find - so this may only name suites
-// the templates actually carry.
-//
-// The suite sits under test/feature/<name>/ so that it belongs to the
-// feature (helpers/featureSource), exactly as go's tm/go/test/feature/
-// secrets/ and rust's tests/feature/secrets/ do; and it is wired only for
-// a feature that is ACTIVE for this target, which is when its build modules
-// (below) exist for the suite to reach.
-//
-// Each suite gets its OWN build step (`zig build test-<name>`) as well as a
-// place in the all-tests `test` step: the corpus suites need a project's
-// compiled `.sdk/test/test.json` beside the SDK, so a checker that has the
-// feature but no corpus (sdkgen's own generatedcompile lane) can still run
-// the feature suite alone and read its count.
 const FEATURE_TESTS: Record<string, string> = {
   secrets: 'test/feature/secrets/secrets_test.zig',
 }
 
 
-// The GATED features' build modules: what a feature's `@import("<name>")`
-// lines resolve to, declared only when the feature is active. Each entry is
-// the block of build.zig statements that wires one feature; `secrets` is
-// the first and, today, the only one.
-//
-// Upstream's own three-module boundary (sekreto's zig Makefile builds
-// exactly these): `plugin` (voxgig/plugin, rooted at its consumer root),
-// `sekreto` (the core, which imports `plugin` by name and nothing under
-// plugins/), and `sekretoplugins`, rooted at the GENERATED
-// feature/secrets/plugins.zig (Config_zig FeaturePlugins) so that only the
-// selected kinds are compiled. The sdk module gets `sekreto` and
-// `sekretoplugins`; the feature file reaches `plugin` through
-// `sekreto.plugin`, so it needs no import of its own.
 const FEATURE_MODULES: Record<string, string> = {
   secrets: `// The secrets feature's vendored libraries (@voxgig/sekreto and
 // voxgig/plugin at the shared vendor tag), as the three named modules
@@ -106,23 +76,6 @@ const Main = cmp(async function Main(props: any) {
   // helpers/applicability.
   const feature = targetFeatures(model, target)
 
-  // THE PLUGIN TRIM FOR AN INACTIVE FEATURE (the scala shape, for the same
-  // reason). pluginExcludes(model) walks only the model's ACTIVE features,
-  // which is right for a target whose feature trim is on: an inactive
-  // feature's whole tree is already gone at `target add`. zig's feature trim
-  // is OFF (model/target/zig.aon `feature: { trim: false }` - root.zig's
-  // built-in exports are static), so an inactive feature's tree is all still
-  // here, and its provider plugins are the part that costs the most. EVERY
-  // declared group of an inactive feature goes, not just the groups marked
-  // inactive: a feature that is off has no active plugins whatever its
-  // `plugin` map says, because targetFeatures drops the feature before
-  // Config ever reads a group. What stays is the two vendored cores and the
-  // ungrouped httpjson/sigv4 helpers - dead files zig never analyses, since
-  // build.zig declares no module rooted in them (FEATURE_MODULES).
-  //
-  // Rooting matches pluginExcludes': zig's declared paths are
-  // target-root-relative, which is this Copy's root, and the other targets'
-  // paths in the same list cannot match anything in a zig tree.
   const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
   const allfeature = getModelPath(model, `main.${KIT}.feature`,
     { required: false, only_active: false }) || {}
@@ -140,23 +93,10 @@ const Main = cmp(async function Main(props: any) {
     }
   }
 
-  // build.zig.zon — the package manifest, stamped with the model package name.
   Package({ target })
 
   Gitignore({})
 
-  // Copy tm/zig files with replacements. The tm src/ subtree only stages the
-  // per-feature custom-source dirs (target add), so it is excluded here
-  // exactly like the go/rust targets. build.zig.zon is generated by Package
-  // (above), so it is excluded from the verbatim copy. The SDK source lives at
-  // the tree root (core/, feature/, utility/, entity/, test/) — Zig's
-  // idiomatic src/ is not used, to keep the exclude rule identical to the
-  // reference targets.
-  //
-  // build.zig and root.zig are NOT in tm/zig any more: both carry
-  // model-driven slots (a gated feature's build modules, test step and root
-  // export) and are emitted below from src/cmp/zig/fragment/, the way
-  // core/sdk.zig always was.
   Copy({
     from: 'tm/' + target.name,
     // pluginExcludes: the generate-time plugin trim for an ACTIVE feature's
@@ -185,11 +125,6 @@ const Main = cmp(async function Main(props: any) {
 
   const fragdir = Path.normalize(__dirname + '/../../../src/cmp/zig/fragment/')
 
-  // build.zig: the template with its two slots filled - a gated feature's
-  // modules after the sdk module, and its test suite as a step of its own
-  // that the all-tests step also depends on. Both empty for a model that
-  // activates no gated feature, which leaves the file byte-identical to the
-  // fragment minus the marker lines.
   File({ name: 'build.zig' }, () => {
     Fragment({
       from: fragdir + 'Build.fragment.zig',
@@ -232,8 +167,6 @@ const Main = cmp(async function Main(props: any) {
     })
   })
 
-  // root.zig: the module root, with the gated features' type exports
-  // appended to the static built-in ones.
   File({ name: 'root.zig' }, () => {
     Fragment({
       from: fragdir + 'Root.fragment.zig',
@@ -242,7 +175,6 @@ const Main = cmp(async function Main(props: any) {
 
         '#FeatureExports': ({ indent }: any) => {
           for (const fname of extraFeatures) {
-            // MUST match Config_zig's make_feature spelling of the type.
             const tname = fname.charAt(0).toUpperCase() + fname.slice(1)
             Content({ indent },
               `pub const ${tname}Feature = @import("feature/${fname}.zig").${tname}Feature;\n`)
@@ -260,19 +192,6 @@ const Main = cmp(async function Main(props: any) {
   // branded error type (error.zig) is a plain template (copied above).
   Folder({ name: 'core' }, () => {
 
-    // core/prepare_auth.zig is GENERATED, not copied from tm/zig: where the
-    // credential goes (header / query / cookie, and under what name) is a
-    // fact about the API, and the template it was extracted from -
-    // tm/zig/core/utility.zig - could only hold one answer. See
-    // PrepareAuth_zig.
-    //
-    // INSIDE THIS `core` FOLDER, and the component opens none of its own -
-    // the Config_zig arrangement, for the same reason. The extracted body
-    // lived in core/utility.zig, which `Copy({from: 'tm/zig'})` lands at
-    // `<root>/core/`, and core/utility.zig re-exports the function with a
-    // SIBLING-relative `@import("prepare_auth.zig")`. A second Folder here
-    // would write core/core/prepare_auth.zig, which that import cannot
-    // reach and `zig build` never analyses.
     PrepareAuth({ target })
 
     File({ name: 'sdk.' + target.ext }, () => {
@@ -285,7 +204,6 @@ const Main = cmp(async function Main(props: any) {
           }
         },
 
-        // Entity accessors - injected at SLOT
         () => {
           each(entity, (ent: ModelEntity) => {
             MainEntity({ target, entity: ent })
@@ -294,6 +212,8 @@ const Main = cmp(async function Main(props: any) {
     })
 
     Config({ target })
+
+    Schema({ target })
   })
 
 })

package/project/.sdk/src/cmp/zig/Package_zig.ts

@@ -15,28 +15,6 @@ import type {
 import { zigModuleName, zigPackageFingerprint } from './utility_zig'
 
 
-// build.zig.zon — the Zig package manifest. Zig has no central package
-// registry, so there are no external registry dependencies to declare: the
-// voxgig struct port is vendored in-tree (utility/voxgigstruct) and wired as a
-// local module by build.zig. This generator only stamps the manifest with the
-// model-derived package name (the go/rust Package generators emit go.mod /
-// Cargo.toml the same way).
-//
-// The `.paths` allow-list mirrors the (registry-less) template: it only
-// matters when packaging for a registry, which zig does not do, so it is kept
-// stable.
-//
-// TOOLCHAIN: zig 0.16. `.name` is an ENUM LITERAL (`.solar_sdk`), and a
-// `.fingerprint` is required beside it. That pairing is what a modern zig
-// wants: 0.14 rejects the older plain-string form outright —
-// `build.zig.zon:2:13: error: expected enum literal` — and 0.13 rejects the
-// enum-literal form, so the two cannot both be supported from one generator.
-// A move BACK to 0.13 would mean reverting both fields here and the CI pin in
-// create-sdkgen project/standard/.github/workflows/ci.yml together.
-//
-// The fingerprint is derived from the package name, not random, so
-// regenerating the same model does not rewrite this file — see
-// zigPackageFingerprint for why, and for what zig checks.
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
   const target = props.target

package/project/.sdk/src/cmp/zig/PrepareAuth_zig.ts

@@ -16,48 +16,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. The zig peer of PrepareAuth_ts; read that one
-// first, it carries the full account of the defect.
-//
-// zig differs from the other twelve ports in ONE way: it had no
-// prepare_auth template to delete. The logic was EMBEDDED in
-// `tm/zig/core/utility.zig` — three file-scope constants and a
-// `pub fn prepare_auth_util` in the middle of a 1500-line module that also
-// holds make_spec, make_url, the result builders and the Utility bundle
-// itself. So this is an EXTRACTION, not a replacement:
-//
-//   core/prepare_auth.zig   GENERATED here, one function.
-//   core/utility.zig        keeps
-//                             pub const prepare_auth_util =
-//                                 @import("prepare_auth.zig").prepare_auth_util;
-//
-// THE OWN-FILE SHAPE, not the whole-module-as-a-component fallback. A zig
-// file IS a struct, so a function in its own file is a first-class
-// compilation unit reached by a relative `@import` — no build.zig entry, no
-// module declaration, nothing to register. Generating the whole of
-// utility.zig instead would turn 1500 lines of hand-maintained template
-// into a TypeScript string for the sake of 40, which is the opposite of the
-// trade the other targets made.
-//
-// THE BINDING DOES NOT MOVE. Three call sites name this symbol and all three
-// keep resolving to it through the re-export:
-//   - `Utility.prepare_auth` (core/utility.zig) — the method the pipeline
-//     dispatches through, called by core/sdk.zig (Main.fragment.zig line
-//     `self.sdkUtility.prepare_auth(ctx)`) and asserted on by
-//     test/pipeline_test.zig.
-//   - `make_spec_util` (core/utility.zig) — `try prepare_auth_util(ctx)`,
-//     unqualified, so the file-scope const is what it finds.
-//   - `sdk.utilmod.prepare_auth_util` — root.zig exports core/utility.zig as
-//     `utilmod`, and test/primary_utility_test.zig drives the shared
-//     corpus's `prepareAuth` section through it.
-//
-// A template cannot fix the defect, 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 — and zig makes that
-// stricter than most: an unused LOCAL is a compile error, so a file that
-// bound `auth_prefix` and then dropped it for a query placement would not
-// build at all.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -65,35 +23,9 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const active = isAuthActive_zig(model)
   const where = resolveAuthIn(model)
   const name = resolveAuthName(model)
-  // Read so the resolution is visible at generation time even though the
-  // emitted code takes the prefix from `options.auth.prefix` at RUNTIME -
-  // it has to, because the secrets feature rewrites it there.
   const prefix = resolveAuthPrefix(model)
   const basic = isHttpBasicAuth(model)
 
-  // FOLDER NESTING — NO Folder IS OPENED HERE, and that is worked out from
-  // two facts, not assumed.
-  //
-  // 1. The template this extracts from is `tm/zig/core/utility.zig`, and
-  //    Main_zig's `Copy({from: 'tm/zig'})` runs at the TARGET ROOT with no
-  //    folder open (zig's layout is flat there: core/, feature/, utility/,
-  //    entity/, test/ — Main_zig's own comment says the idiomatic src/ is
-  //    deliberately not used). So that template lands at `<root>/core/`,
-  //    and the extracted function must land in the same directory for
-  //    `@import("prepare_auth.zig")` — a SIBLING-relative path — to resolve.
-  //
-  // 2. Main_zig ALREADY opens `Folder({name: 'core'})` for core/sdk.zig and
-  //    for Config, and that is where this component is called. Config_zig
-  //    writes `File({name: 'config.zig'})` with no Folder of its own for
-  //    exactly this reason.
-  //
-  // Opening a second `core` here would write `core/core/prepare_auth.zig`:
-  // a file no `@import` names, invisible to `zig build` (which analyses only
-  // what a module root reaches), while core/utility.zig's re-export fails to
-  // resolve — or, worse in the ts port's version of this trap, silently
-  // keeps using a stale sibling. Verified by generating the target and
-  // running `zig build test` against the result, not by eye: a file zig
-  // never reaches produces no error at all.
   File({ name: 'prepare_auth.' + target.ext }, () => {
     Content(render({ active, where, name, prefix, basic }))
   })
@@ -124,9 +56,6 @@ const HEAD = `// prepare_auth — GENERATED from the model (src/cmp/zig/PrepareA
 
 
 function render(spec: AuthSpec): string {
-  // NO GENERATION-TIME GATE ON WHETHER TO PLACE A CREDENTIAL AT ALL, beyond
-  // the project's own explicit switch — see isAuthActive_zig below for why
-  // `isAuthActive` is the wrong predicate here.
   if (!spec.active) return renderInactive()
 
   if ('query' === spec.where) return renderQuery(spec)
@@ -136,11 +65,6 @@ function render(spec: AuthSpec): string {
 }
 
 
-// AUTH SWITCHED OFF BY THE PROJECT (`main.kit.config.auth.active: false`).
-// The SDK gets a prepare_auth that is honest about it rather than one that
-// deletes a header nobody set. Nothing but the Context and Spec types is
-// imported: zig tolerates an unused file-scope const, but a reader should
-// not have to decide whether `vs` here means something.
 function renderInactive(): string {
   return HEAD + `//
 // THIS SDK SENDS NO CREDENTIAL: the project set
@@ -164,10 +88,6 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
 }
 
 
-// HEADER — the default, and BYTE-FOR-BYTE the body that was in
-// core/utility.zig when the scheme resolves to header/Authorization. Only
-// the constant's VALUE moves with the model, plus the HTTP Basic block,
-// which is emitted only for a basic scheme.
 function renderHeader(spec: AuthSpec): string {
   const withBasic = spec.basic
 
@@ -225,10 +145,6 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
 }
 
 
-// QUERY — the credential is a query parameter, so it goes in spec.query and
-// the header bag is never touched. No `fmt`, because nothing is joined:
-// zig would accept an unused file-scope helper, but emitting one invites the
-// reader to look for the concatenation that is deliberately absent.
 function renderQuery(spec: AuthSpec): string {
   return HEAD + imports({ vs: true, fmt: false }) +
     facts(spec.where, false, true) + `
@@ -367,10 +283,6 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
 }
 
 
-// The imports and type aliases, in core/utility.zig's own order and
-// spelling. `E` comes from helpers rather than error.zig on purpose:
-// error.zig's type is `ProjectNameError`, and the placeholder rewrite is
-// applied by Copy, which this GENERATED file never travels through.
 function imports(need: { vs: boolean, fmt: boolean }): string {
   return `
 const std = @import("std");
@@ -391,8 +303,6 @@ fn fmt(comptime f: []const u8, args: anytype) []const u8 {
 }
 
 
-// Emitted only for a basic scheme in a HEADER placement, so an ordinary
-// bearer SDK carries neither the base64 encoder nor the boolean coercion.
 function basicHelpers(): string {
   return `
 // Boolean-or-absent: an option that is unset, null or a non-boolean is false
@@ -461,40 +371,11 @@ function basicBlock(): string {
 }
 
 
-// The credential's key, as it goes into the bag.
-//
-// A HEADER name is LOWERCASED. HTTP header names are case-insensitive on the
-// wire (RFC 9110 5.1), but this SDK's header bag is a plain Value map and
-// object keys are case-SENSITIVE: the extracted template said
-// `const HEADER_AUTH = "authorization";`, the shared corpus asserts
-// `ctx:spec:headers:authorization`, tm/zig/test/pipeline_test.zig reads
-// `h.getp(ctx.spec.?.headers, "authorization")`, and feature/secrets.zig
-// rewrites the same lowercase key. apidef writes `name: "Authorization"`, so
-// emitting it verbatim would put the credential where none of those look.
-//
-// A QUERY parameter and a COOKIE name are case-SENSITIVE to the API itself,
-// so those go in exactly as the spec spells them: `?token=` is not `?Token=`.
 function credLiteral(where: string, name: string): string {
   return 'header' === where ? String(name).toLowerCase() : String(name)
 }
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING. That helper is also
-// false whenever the SPEC declares no security scheme
-// (`main.kit.info.auth: false`) — a statement about the DEFINITION, not a ban
-// on ever sending a credential. Such an SDK still carries one: `optspec`
-// always declares `apikey`, and make_options_util fills `options.auth` from
-// the optspec defaults (tm/zig/core/utility.zig), so the runtime
-// `h.is_noval(auth)` guard never fired and every such SDK has always sent
-// `options.apikey`. Gating the body on `isAuthActive` does not trim dead
-// code, it silently removes working authentication — and takes the secrets
-// feature with it, since that resolves a secret into `options.apikey` and
-// prepare_auth then places nothing. zig's own gated suite
-// (`zig build test-secrets`) pins exactly that.
-//
-// `main.kit.config.auth.active: false` is the project saying "this SDK sends
-// no credential, ever". It is the only signal that can honestly be honoured
-// before runtime, so it is the only one used here.
 function isAuthActive_zig(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -502,23 +383,6 @@ function isAuthActive_zig(model: any): boolean {
 }
 
 
-// THE PLACEMENT AS A COMPTIME FACT, exported beside the function.
-//
-// The generated body has exactly ONE branch, chosen here at generation time,
-// and nothing downstream can tell which by looking at the options: a query
-// SDK's `options.auth.in` says "query", but an auth-OFF SDK is
-// indistinguishable from a header one there (Config omits `options.auth`
-// entirely when auth is inactive, and make_options' optspec then supplies the
-// same empty defaults either way).
-//
-// tm/zig/test/pipeline_test.zig needs to tell them apart. Its prepare_auth
-// cases assert the HEADER shape - `spec.headers["authorization"]` - which is
-// the right assertion for the default and the wrong one for the other three,
-// where the SDK correctly places nothing there. Rather than let a query SDK
-// ship four red tests (or delete the coverage that every header SDK does
-// want), the suite reads these two constants and skips what does not apply.
-//
-// core/utility.zig re-exports both, so the path is `sdk.utilmod.<name>`.
 function facts(where: string, basic: boolean, active: boolean): string {
   const placement = active ? where : 'none'
 

package/project/.sdk/src/cmp/zig/ReadmeExamplesTest_zig.ts

@@ -2,24 +2,6 @@
 import { cmp, Content } from '@voxgig/sdkgen'
 
 
-// Validates the documented README/REFERENCE quick-start examples for the Zig
-// SDK.
-//
-// DESIGN NOTE vs the go/rust gates (ReadmeExamplesTest_go.ts /
-// ReadmeExamplesTest_rust.ts): the go version shells out to `go build`/`go run`
-// to compile and run every fenced block; the rust version reads the doc files
-// and checks that each block is structurally well-formed. Zig's test harness
-// uses an EXPLICIT test-file list in build.zig (no auto-discovery of test/*.zig
-// and no per-block temp compilation), and the doc files are not on the package
-// path at test time — so neither a filesystem scan nor a per-snippet compile can
-// be authored safely without a build to validate against.
-//
-// Instead this gate emits a real, always-compiling zig `test` block INTO the
-// shared generated_test.zig (the only generated test file build.zig picks up).
-// It exercises the exact top-level entry points the docs advertise — the
-// test-mode constructor and the `direct()` escape hatch — so the documented
-// quick-start surface is guaranteed to exist and run. Upgrading it to a true
-// per-block compile gate is left as a follow-up.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { ctx$: { model } } = props
 

package/project/.sdk/src/cmp/zig/ReadmeQuick_zig.ts

@@ -154,9 +154,6 @@ switch (client.${method}(h.vnull()).load(${loadArg}, h.vnull())) {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
     }
-    // The id VALUE for an update/remove match: a type-correct literal (zig
-    // ops return an OpResult, so threading the created record's id through a
-    // switch scope would obscure the example).
     const idValueFor = (opname: string): string => zigLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {

package/project/.sdk/src/cmp/zig/ReadmeRef_zig.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 {
@@ -39,7 +39,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)
 
@@ -390,9 +390,6 @@ const client = sdk.${model.const.Name}SDK.new(h.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/zig/Schema_zig.ts

@@ -0,0 +1,91 @@
+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.zig, in core, and for the same reason: core owns the
+  // generated data, so nothing in utility or feature has to reach up for it.
+  File({ name: '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.
+
+const h = @import("helpers.zig");
+const jsonparse = @import("../utility/jsonparse.zig");
+const Value = h.Value;
+
+const OPTSPEC_DATA: []const u8 = ${JSON.stringify(JSON.stringify(optspec))};
+
+const ENTITYSPEC_DATA: []const u8 = ${JSON.stringify(JSON.stringify(entityspec))};
+
+/// The option spec make_options validates client options against.
+///
+/// Unreachable on error: the constant is generated by a JSON serialiser and
+/// never edited by hand. Panicking beats returning an empty spec, which would
+/// validate everything and fail far from the cause.
+pub fn make_optspec() Value {
+    return jsonparse.json_parse(OPTSPEC_DATA) catch
+        @panic("${model.const.Name}: embedded option spec is not valid JSON");
+}
+
+/// Per-entity data and request specs, keyed by entity name.
+pub fn make_entityspec() Value {
+    return jsonparse.json_parse(ENTITYSPEC_DATA) catch
+        @panic("${model.const.Name}: embedded entity spec is not valid JSON");
+}
+
+// SHARED SPECS, the shape 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. Value nodes are arena-allocated and
+// reference-stable, so the shared value is genuinely one structure.
+//
+// The returned Values SHARE their nodes: treat them as read-only.
+// make_options validates AGAINST the spec and writes into the options, never
+// into the spec.
+var shared_optspec_val: ?Value = null;
+var shared_entityspec_val: ?Value = null;
+
+/// The process-wide option spec, built once on first use.
+pub fn shared_optspec() Value {
+    if (shared_optspec_val) |s| return s;
+    const s = make_optspec();
+    shared_optspec_val = s;
+    return s;
+}
+
+/// The process-wide entity specs, built once on first use.
+pub fn shared_entityspec() Value {
+    if (shared_entityspec_val) |s| return s;
+    const s = make_entityspec();
+    shared_entityspec_val = s;
+    return s;
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/zig/TestDirect_zig.ts

@@ -4,17 +4,6 @@ import { cmp, Content } from '@voxgig/sdkgen'
 import { zigVarName } from './utility_zig'
 
 
-// Per-entity direct-call smoke tests. Emits `test "..."` blocks INTO the
-// shared generated_test.zig file (opened by Test_zig) — see TestEntity_zig for
-// why zig keeps every generated test in one file.
-//
-// The go/rust TestDirect generators build a per-entity mock-fetch harness and
-// assert the exact URL/params the entity's op point resolves. Reproducing that
-// path-extraction + mock-transport harness in zig safely requires a build to
-// validate against, so this generator instead exercises the documented
-// `direct()` / `prepare()` escape hatches through the offline test transport
-// and asserts the result shape. `std`, `sdk`, `h`, `Value` and `vnull()` are
-// in scope from the Test_zig header.
 const TestDirect = cmp(function TestDirect(props: any) {
   const { entity } = props
 

package/project/.sdk/src/cmp/zig/TestEntity_zig.ts

@@ -4,14 +4,6 @@ import { cmp, Content } from '@voxgig/sdkgen'
 import { zigVarName } from './utility_zig'
 
 
-// Per-entity model-driven smoke tests. Emits `test "..."` blocks INTO the
-// shared generated_test.zig file (opened by Test_zig) — zig's build.zig uses
-// an explicit test-file list, so every generated test must live in that one
-// file rather than a per-entity file (the go/rust one-file-per-entity layout
-// relies on cargo/go auto-discovery, which zig lacks). Each test drives the
-// entity through the full pipeline via the offline `test` transport and
-// asserts a non-error result. `std`, `sdk`, `h`, `Value` and `vnull()` are in
-// scope from the Test_zig header.
 const TestEntity = cmp(function TestEntity(props: any) {
   const { target, entity } = props
 

package/project/.sdk/src/cmp/zig/Test_zig.ts

@@ -10,17 +10,6 @@ import { TestDirect } from './TestDirect_zig'
 import { ReadmeExamplesTest } from './ReadmeExamplesTest_zig'
 
 
-// Generated tests. The bulk of behavioural coverage lives in the hand-written
-// template suite (test/*.zig, copied verbatim): the struct corpus, the
-// pipeline, every feature, and the cross-language gotchas. Here we emit the
-// model-driven smoke tests.
-//
-// zig's build.zig picks up an EXPLICIT test-file list, so every generated test
-// must land in the single `test/generated_test.zig` file it already lists —
-// the per-entity generators (TestEntity, TestDirect) and the readme-examples
-// gate all emit their `test` blocks INTO this one open File rather than opening
-// their own (the go/rust one-file-per-entity split relies on auto-discovery
-// zig does not have).
 const Test = cmp(function Test(props: any) {
   const { model } = props.ctx$
   const { target } = props