@voxgig/sdkgen 3.4.7 → 3.5.0

package/model/sdkgen.aontu

@@ -142,11 +142,39 @@ main: kit: contributor: &: {
 }
 
 
+# PROVENANCE: where a copied target or feature came from.
+#
+# `target add` / `feature add` copy a shipped definition into a project and
+# stamp these three keys into the copy, by rewriting the `base: 'BASE'` line
+# the shipped file carries as an anchor:
+#
+#   base      the `.sdk` folder the copy came from, relative to the project
+#             (absolute only for an out-of-tree source). '/'-normalised, so a
+#             project resynced on Windows and on Linux records the same value.
+#   origname  the name in the SOURCE, when installed under a different one
+#             (`target add go~go2` -> origname 'go'). Empty when they match.
+#   package   the sdkgen package that provided it, when the source declared
+#             one. Empty otherwise.
+#
+# Read by `feature add` (to find each target's template tree) and by `doctor`
+# (to re-resolve the scaffold a copy should be compared against). Without
+# them both fall back to the bundled scaffold, which is right only while
+# everything ships inside @voxgig/sdkgen.
+#
+# DEFAULTED, deliberately. A bare `string` inside a `&:` spread makes the key
+# REQUIRED, which would fail the model compile of every project whose copies
+# predate this — and `origname`/`package` are stamped only when they apply,
+# so it would fail every ordinary install too. `*''` also keeps them FALSY
+# when unset, which is what the two readers already test for.
 main: kit: target: &: {
   name: key()
   active: *true | boolean
   ext: string
   comment: line: string
+
+  base:     *'' | string
+  origname: *'' | string
+  package:  *'' | string
   module: {
     name: string
 
@@ -361,6 +389,11 @@ main: kit: feature: &: {
   active: *false | boolean
   title: string
 
+  # Provenance — see the note on `main: kit: target: &:` above.
+  base:     *'' | string
+  origname: *'' | string
+  package:  *'' | string
+
   # TODO: version '0.0.1' | semver # where semver is a string format type as per semver.org
   version: *'0.0.1' | string
 
@@ -401,3 +434,39 @@ main: kit: option: &: {
 
 
 
+# DOCS ITEMS — the third kind. See docs/design/sdkgen-packages.md §20.
+#
+# A docs item is a generation target whose destination is a DOCUMENTATION
+# SYSTEM rather than a language: a static site, a developer-portal catalogue,
+# a hosted service's config. sdkgen ships the kind; the items live in
+# packages, so this spread declares only what EVERY destination needs and
+# leaves the rest to the item's own model file (an unknown key unifies fine).
+#
+# Deliberately NOT copied from the target spread: `ext`, `comment.line` and
+# `module.name` are required there and have no honest value for a site
+# emitting .md, .yml, .css and .svg at once. `title` is defaulted rather than
+# required, so an author is never forced to invent one to make the model
+# compile — the `module.name` trap of §10.1.
+main: kit: docs: &: {
+  name: key()
+  active: *true | boolean
+  title: *'' | string
+
+  # Provenance — see the note on `main: kit: target: &:` above. Written by
+  # `docs add`, read by doctor, `package list` and `package update`.
+  base:     *'' | string
+  origname: *'' | string
+  package:  *'' | string
+
+  # Where the item generates. '' is in-tree, at `<sdk-repo>/<name>/`;
+  # anything else is its own generate() pass rooted there, exactly as for a
+  # target (see explanation/out-of-tree-targets). Out of tree is the normal
+  # case for a docs item: a documentation site usually has its own repo, and
+  # in-tree it would collide with the SDK repo's own README and workflows.
+  output: {
+    path: *'' | string
+    repo: *'' | string
+    adopt: *false | boolean
+    sdkrel: *'' | string
+  }
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "3.4.7",
+  "version": "3.5.0",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "types": "dist/sdkgen.d.ts",
   "description": "Voxgig SDK Generator.",
@@ -24,6 +24,7 @@
   "scripts": {
     "test": "node --enable-source-maps --test dist-test/**/*.test.js",
     "test-some": "node --enable-source-maps --test-name-pattern=\"$npm_config_pattern\" --test dist-test/**/*.test.js",
+    "golden": "npm run build && SDKGEN_GOLDEN_UPDATE=1 node --test dist-test/characterize.test.js",
     "watch": "tsc --build src test -w",
     "build": "tsc --build src test && npm run check-scaffold && npm run stage-scaffold",
     "clean": "rm -rf dist dist-test node_modules yarn.lock package-lock.json",

package/project/.sdk/model/feature/audit.aontu

@@ -5,6 +5,7 @@ main: kit: feature: audit: {
   title: "Structured audit trail of operations"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/cache.aontu

@@ -5,6 +5,7 @@ main: kit: feature: cache: {
   title: "Response caching for safe read requests"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/clienttrack.aontu

@@ -5,6 +5,7 @@ main: kit: feature: clienttrack: {
   title: "Client identity and per-request correlation headers"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/debug.aontu

@@ -5,6 +5,7 @@ main: kit: feature: debug: {
   title: "Request/response capture ring buffer for debugging"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/idempotency.aontu

@@ -5,6 +5,7 @@ main: kit: feature: idempotency: {
   title: "Idempotency keys for safe retries of mutating operations"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/log.aontu

@@ -5,6 +5,7 @@ main: kit: feature: log: {
   title: "Structured request and response logging"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
 
   config: {

package/project/.sdk/model/feature/metrics.aontu

@@ -5,6 +5,7 @@ main: kit: feature: metrics: {
   title: "Statistics capture: per-operation counters and latency"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/netsim.aontu

@@ -5,6 +5,7 @@ main: kit: feature: netsim: {
   title: "Network behaviour simulation for offline testing (latency, failures, outages)"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     # Test-support feature: enable per test via

package/project/.sdk/model/feature/paging.aontu

@@ -5,6 +5,7 @@ main: kit: feature: paging: {
   title: "Pagination signals for list operations"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/proxy.aontu

@@ -5,6 +5,7 @@ main: kit: feature: proxy: {
   title: "Outbound HTTP(S) proxy routing"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/ratelimit.aontu

@@ -5,6 +5,7 @@ main: kit: feature: ratelimit: {
   title: "Client-side rate limiting via a token bucket"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/rbac.aontu

@@ -5,6 +5,7 @@ main: kit: feature: rbac: {
   title: "Client-side role/permission enforcement"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/retry.aontu

@@ -5,6 +5,7 @@ main: kit: feature: retry: {
   title: "Automatic retry of transient failures with exponential backoff"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     # Opt-in: enable per SDK via options.feature.retry.active = true

package/project/.sdk/model/feature/streaming.aontu

@@ -5,6 +5,7 @@ main: kit: feature: streaming: {
   title: "Incremental streaming of list results via async iteration"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/telemetry.aontu

@@ -5,6 +5,7 @@ main: kit: feature: telemetry: {
   title: "Distributed tracing spans with W3C trace-context propagation"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/feature/test.aontu

@@ -5,6 +5,7 @@ main: kit: feature: test: {
   title: "In-memory mock transport for testing without a live server"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     # Test mode is not active by default, unlike most features

package/project/.sdk/model/feature/timeout.aontu

@@ -5,6 +5,7 @@ main: kit: feature: timeout: {
   title: "Per-request timeout with transport abort"
   version: '0.0.1'
   active: true
+  base: 'BASE'
 
   config: {
     options: {

package/project/.sdk/model/target/c.aontu

@@ -5,6 +5,7 @@ main: kit: target: c: {
   ext: c
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/clojure.aontu

@@ -5,6 +5,7 @@ main: kit: target: clojure: {
   ext: clj
   comment: line: ";"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/cpp.aontu

@@ -5,6 +5,7 @@ main: kit: target: cpp: {
   ext: hpp
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/dart.aontu

@@ -4,6 +4,7 @@ main: kit: target: dart: {
   ext: dart
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/elixir.aontu

@@ -5,6 +5,7 @@ main: kit: target: elixir: {
   ext: ex
   comment: line: "#"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/go-cli.aontu

@@ -11,6 +11,7 @@ main: kit: target: 'go-cli': {
   ext: go
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
 
   # Per-generation-phase activation. Mirrors the feature pattern
   # (`main.kit.feature.<name>: { active: true }`). Root.ts inspects

package/project/.sdk/model/target/go-mcp.aontu

@@ -11,6 +11,7 @@ main: kit: target: 'go-mcp': {
   ext: go
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
 
   # Per-generation-phase activation. Mirrors go-cli — only Main runs.
   phase: {

package/project/.sdk/model/target/go.aontu

@@ -5,6 +5,7 @@ main: kit: target: go: {
   ext: go
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/haskell.aontu

@@ -5,6 +5,7 @@ main: kit: target: haskell: {
   ext: hs
   comment: line: "--"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   # Entities are generic (config-driven F.makeEntity), so no per-entity or

package/project/.sdk/model/target/java.aontu

@@ -4,6 +4,7 @@ main: kit: target: java: {
   ext: java
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/js.aontu

@@ -5,6 +5,7 @@ main: kit: target: js: {
   ext: js
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
 
   deps: &: {
     # TODO: fix aontu disjunctions!

package/project/.sdk/model/target/kotlin.aontu

@@ -4,6 +4,7 @@ main: kit: target: kotlin: {
   ext: kt
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/lean.aontu

@@ -5,6 +5,7 @@ main: kit: target: lean: {
   ext: lean
   comment: line: "--"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   # Entities are generic (config-driven F.makeEntity), so no per-entity or

package/project/.sdk/model/target/lua.aontu

@@ -5,6 +5,7 @@ main: kit: target: lua: {
   ext: lua
   comment: line: "--"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/ocaml.aontu

@@ -5,6 +5,7 @@ main: kit: target: ocaml: {
   ext: ml
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/perl.aontu

@@ -5,6 +5,7 @@ main: kit: target: perl: {
   ext: pl
   comment: line: "#"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/php.aontu

@@ -5,6 +5,7 @@ main: kit: target: php: {
   ext: php
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/py-data.aontu

@@ -14,6 +14,7 @@ main: kit: target: 'py-data': {
   ext: py
   comment: line: "#"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   # Per-generation-phase activation. Mirrors go-cli/go-mcp: every standard

package/project/.sdk/model/target/py.aontu

@@ -5,6 +5,7 @@ main: kit: target: py: {
   ext: py
   comment: line: "#"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/rb.aontu

@@ -5,6 +5,7 @@ main: kit: target: rb: {
   ext: rb
   comment: line: "#"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/rust.aontu

@@ -5,6 +5,7 @@ main: kit: target: rust: {
   ext: rs
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/scala.aontu

@@ -4,6 +4,7 @@ main: kit: target: scala: {
   ext: scala
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   deps: &: {

package/project/.sdk/model/target/seneca-provider.aontu

@@ -27,6 +27,7 @@ main: kit: target: 'seneca-provider': {
   ext: ts
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   # Per-generation-phase activation. Mirrors py-data: every standard phase is

package/project/.sdk/model/target/zig.aontu

@@ -5,6 +5,7 @@ main: kit: target: zig: {
   ext: zig
   comment: line: "//"
   module: name: '$$name$$'
+  base: 'BASE'
   srcfeature: false
 
   # The vendored voxgig struct port is in-tree (utility/voxgigstruct) — Zig

package/project/.sdk/src/cmp/c/Config_c.ts

@@ -116,6 +116,28 @@ voxgig_value* make_config(void) {
   return json_parse(CONFIG_DATA);
 }
 
+// SHARED CONFIG (sdkgen rung L2).
+//
+// The SDK reads the config on every request and never writes to it, so one
+// instance is shared by every client rather than rebuilt per client. Above the
+// size threshold make_config re-parses the whole embedded JSON, so this is the
+// difference between parsing the model once and once per client.
+//
+// Deliberately never freed: it lives for the life of the process, like any
+// other program-lifetime singleton.
+static voxgig_value* shared_config_val = NULL;
+
+// The process-wide config, built once on first use.
+//
+// The returned value is SHARED: treat it as read-only. Callers that need to
+// mutate should use make_config, which always returns a fresh copy.
+voxgig_value* shared_config(void) {
+  if (NULL == shared_config_val) {
+    shared_config_val = make_config();
+  }
+  return shared_config_val;
+}
+
 Feature* make_feature(const char* name) {
 `)
     }
@@ -131,6 +153,28 @@ voxgig_value* make_config(void) {
   return ${formatCValue(config, 1)};
 }
 
+// SHARED CONFIG (sdkgen rung L2).
+//
+// The SDK reads the config on every request and never writes to it, so one
+// instance is shared by every client rather than rebuilt per client. Above the
+// size threshold make_config re-parses the whole embedded JSON, so this is the
+// difference between parsing the model once and once per client.
+//
+// Deliberately never freed: it lives for the life of the process, like any
+// other program-lifetime singleton.
+static voxgig_value* shared_config_val = NULL;
+
+// The process-wide config, built once on first use.
+//
+// The returned value is SHARED: treat it as read-only. Callers that need to
+// mutate should use make_config, which always returns a fresh copy.
+voxgig_value* shared_config(void) {
+  if (NULL == shared_config_val) {
+    shared_config_val = make_config();
+  }
+  return shared_config_val;
+}
+
 Feature* make_feature(const char* name) {
 `)
     }

package/project/.sdk/src/cmp/c/fragment/Main.fragment.c

@@ -16,7 +16,9 @@ ProjectNameSDK* projectname_sdk_new(voxgig_value* options) {
   sdk->features_cap = 0;
   sdk->rootctx = NULL;
 
-  voxgig_value* config = make_config();
+  /* The process-wide config (sdkgen rung L2): read-only on the request path,
+   * so every client shares one rather than rebuilding it. */
+  voxgig_value* config = shared_config();
 
   CtxSpec cs;
   memset(&cs, 0, sizeof(cs));