@voxgig/sdkgen 4.17.6 → 4.18.0

package/model/sdkgen.aon

@@ -173,6 +173,10 @@ main: kit: target: &: {
   #   sekreto   a vendored sekreto port lives in this target's feature
   #             container, so a feature can resolve secrets through it
   #
+  #   schema    this target emits the generated `Schema` module — the
+  #             model's option spec and per-entity struct.validate specs —
+  #             so a feature can validate against the model's own types
+  #
   # Tags named in the design note but not yet load-bearing
   # (`per-feature-file`, `deps`, `transport-wrap`, `hooks`, `delegates`)
   # are deliberately absent until a feature actually gates on one: a tag
@@ -484,6 +488,32 @@ main: kit: feature: &: {
   # the others.
   spec: &: string
 
+  # THE FEATURE'S OWN OPTION SCHEMA.
+  #
+  # `config.options` is the DEFAULTS map: what happens when the caller says
+  # nothing. It is also the README's option table, and — read by example —
+  # the type of each option in the generated option spec.
+  #
+  # `config.optspec` is for what a default cannot say:
+  #   - an option with NO default (a `sink` callback, an injected clock, a
+  #     value the caller either supplies or does not). Undeclared, these
+  #     were invisible to the spec AND missing from the docs table.
+  #   - an option whose default understates its type. netsim's `latency: 0`
+  #     reads as "a number" while the feature also takes `{ min, max }`.
+  #
+  # Values are struct.validate sentinels — '`$FUNCTION`', '`$MAP`', or a
+  # union ['`$ONE`', '`$NUMBER`', '`$MAP`']. A name in both maps takes its
+  # TYPE from here and its default from `config.options`.
+  #
+  # `config.strict: true` closes the feature's spec, so an option neither
+  # map declares is rejected instead of passed through. Off by default: the
+  # shipped features are not fully declared yet, and rejecting a working
+  # client's option on upgrade is worse than missing a typo.
+  config: {
+    optspec: &: top
+    strict: *false | boolean
+  }
+
   # PLUGINS — a feature's optional, separately-trimmed parts.
   #
   # A feature whose implementation is a thin layer over a library with
@@ -571,6 +601,101 @@ main: kit: option: &: {
 }
 
 
+# THE SDK CLIENT OPTION SCHEMA — one declaration, every target.
+#
+# A struct.validate SPEC, in struct's own by-example vocabulary: a concrete
+# value is BOTH the type constraint and the default (`base` here means "a
+# string, defaulting to http://localhost:8000"), and a `$SENTINEL` constrains
+# without defaulting. The generated `Spec` module carries it into the SDK,
+# where makeOptions validates the caller's options against it.
+#
+# WHY IT MOVED HERE. It used to be a literal inside every language's
+# make_options template — twenty hand-maintained copies of one schema, two of
+# them (cpp, scala) as JSON string constants. Nothing checked them against
+# each other and nothing checked them against the documented option list, so
+# the runtime contract, the twenty copies and the README were three sources
+# of truth for the same thing. A project that adds an option now adds it in
+# ONE place and every ported target validates it.
+#
+# Keys are the option names a caller passes to the constructor. Unknown
+# top-level keys are DROPPED by validate (not rejected) — that is struct's
+# behaviour, not a choice made here, and it is why `extend` needs an entry:
+# without one the constructor's feature-adoption seam silently received
+# nothing.
+main: kit: optspec: {
+
+  # Credentials. '' is the documented "not supplied" value; `auth: null`
+  # suppresses auth outright and is restored AFTER validate (a stored null
+  # reads as "no value", so the default below would otherwise refill it).
+  apikey: ''
+  secret: ''
+
+  # The API base URL. A `{name}` placeholder is resolved from `server`.
+  base: 'http://localhost:8000'
+  prefix: ''
+  suffix: ''
+
+  auth: {
+    prefix: ''
+    basic: false
+  }
+
+  # Extra headers sent with every request: any name, string values.
+  headers: {
+    '`$CHILD`': '`$STRING`'
+  }
+
+  # The operation and method allow-lists, as comma-separated strings.
+  allow: {
+    method: 'GET,PUT,POST,PATCH,DELETE,OPTIONS'
+    op: 'create,update,load,list,remove,command,direct,graphql'
+  }
+
+  # Per-entity overrides. `$OPEN` because an entity entry carries
+  # target-specific keys (aliases, test data) this schema does not enumerate.
+  entity: {
+    '`$CHILD`': {
+      '`$OPEN`': true
+      active: false
+      alias: {}
+    }
+  }
+
+  # Feature INSTANCES supplied at construction (the station adopt path):
+  # class instances, not data, so `$ANY` passes them through verbatim.
+  extend: '`$ANY`'
+
+  # Platform seams. A function value does not survive validate (struct drops
+  # it), so `system.fetch` is captured and restored around the call.
+  utility: {}
+  system: {
+    fetch: '`$ANY`'
+  }
+
+  test: {
+    active: false
+    entity: {
+      '`$OPEN`': true
+    }
+  }
+
+  clean: {
+    keys: 'key,token,id'
+  }
+
+  # Server-variable values for a templated base URL (OpenAPI server
+  # variables). Spec defaults arrive through the generated Config; these are
+  # the caller's overrides.
+  server: {
+    '`$CHILD`': ''
+  }
+
+  # `feature` is NOT declared here. It is assembled per target from each
+  # active feature's own `config.options`, which is already the feature's
+  # by-example schema — see helpers/optspec.
+}
+
+
 
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "4.17.6",
+  "version": "4.18.0",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "engines": {

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

@@ -22,3 +22,18 @@ main: kit: feature: audit: {
     PreUnexpected: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: audit: config: optspec: {
+  # injected clock, so a test can pin the timestamps
+  now: '`$FUNCTION`'
+  # receives every audit record
+  sink: '`$FUNCTION`'
+}

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

@@ -23,3 +23,16 @@ main: kit: feature: cache: {
   # Cache wraps the transport in init(); it dispatches no pipeline hooks.
   hook: {}
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: cache: config: optspec: {
+  # injected clock, for TTL expiry without waiting
+  now: '`$FUNCTION`'
+}

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

@@ -20,3 +20,24 @@ main: kit: feature: clienttrack: {
     PreRequest: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: clienttrack: config: optspec: {
+  # overrides the SDK name sent in the client header
+  clientName: '`$STRING`'
+  # overrides the SDK version sent with it
+  clientVersion: '`$STRING`'
+  # extra headers merged into every tracked request
+  headers: '`$MAP`'
+  # supplies session and request ids
+  idgen: '`$FUNCTION`'
+  # pins the session id instead of generating one
+  sessionId: '`$STRING`'
+}

package/project/.sdk/model/feature/cost.aon

@@ -41,3 +41,18 @@ main: kit: feature: cost: {
     PreUnexpected: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: cost: config: optspec: {
+  # who the spend is attributed to
+  actor: '`$STRING`'
+  # receives every priced attempt
+  sink: '`$FUNCTION`'
+}

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

@@ -25,3 +25,18 @@ main: kit: feature: debug: {
     PreUnexpected: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: debug: config: optspec: {
+  # injected clock, so a trace has stable durations
+  now: '`$FUNCTION`'
+  # receives each trace entry as it is recorded
+  onEntry: '`$FUNCTION`'
+}

package/project/.sdk/model/feature/feature-index.aon

@@ -21,6 +21,7 @@
 @"audit.aon"
 @"clienttrack.aon"
 @"rbac.aon"
+@"validate.aon"
 
 # Test support: network behaviour simulation
 @"netsim.aon"

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

@@ -21,3 +21,16 @@ main: kit: feature: idempotency: {
     PreRequest: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: idempotency: config: optspec: {
+  # supplies the idempotency key
+  keygen: '`$FUNCTION`'
+}

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

@@ -38,3 +38,16 @@ main: kit: feature: log: {
 }
 
 
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: log: config: optspec: {
+  # pino level: 'info' unless set
+  level: '`$STRING`'
+  # an existing logger to use instead of constructing one
+  logger: '`$ANY`'
+}

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

@@ -20,3 +20,16 @@ main: kit: feature: metrics: {
     PreUnexpected: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: metrics: config: optspec: {
+  # injected clock, for deterministic durations
+  now: '`$FUNCTION`'
+}

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

@@ -31,6 +31,20 @@ main: kit: feature: netsim: {
       # hard outage: every call fails at the transport level
       offline: false
     }
+
+    # TYPES for the options whose kind the default cannot state.
+    # `config.optspec` wins over `config.options` when a name is in both, so
+    # the default above still documents the value and this states what the
+    # feature actually accepts.
+    optspec: {
+      # `latency: 0` reads as "a number", but the feature also takes
+      # `{ min, max }` for a uniform sample — the comment above said so and
+      # the spec would have rejected it.
+      latency: ['`$ONE`', '`$NUMBER`', '`$MAP`']
+
+      # Injected clock, for tests that must not really wait.
+      sleep: '`$FUNCTION`'
+    }
   }
 
   # Netsim wraps the transport in init(); it dispatches no pipeline hooks.

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

@@ -30,3 +30,18 @@ main: kit: feature: paging: {
     PreResult: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: paging: config: optspec: {
+  # page size to request
+  limit: '`$NUMBER`'
+  # which operations paginate
+  ops: '`$LIST`'
+}

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

@@ -23,3 +23,16 @@ main: kit: feature: proxy: {
   # Proxy wraps the transport in init(); it dispatches no pipeline hooks.
   hook: {}
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: proxy: config: optspec: {
+  # builds the transport agent for a proxy URL
+  agent: '`$FUNCTION`'
+}

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

@@ -21,3 +21,18 @@ main: kit: feature: ratelimit: {
   # Ratelimit wraps the transport in init(); it dispatches no pipeline hooks.
   hook: {}
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: ratelimit: config: optspec: {
+  # injected clock
+  now: '`$FUNCTION`'
+  # injected delay, so a test need not really wait
+  sleep: '`$FUNCTION`'
+}

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

@@ -23,3 +23,18 @@ main: kit: feature: retry: {
   # Retry wraps the transport in init(); it dispatches no pipeline hooks.
   hook: {}
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: retry: config: optspec: {
+  # randomise the backoff delay
+  jitter: '`$BOOLEAN`'
+  # injected delay, so a test need not really wait
+  sleep: '`$FUNCTION`'
+}

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

@@ -22,3 +22,18 @@ main: kit: feature: streaming: {
     PreResult: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: streaming: config: optspec: {
+  # which operations stream
+  ops: '`$LIST`'
+  # injected delay for paced delivery
+  sleep: '`$FUNCTION`'
+}

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

@@ -21,3 +21,22 @@ main: kit: feature: telemetry: {
     PreUnexpected: active: true
   }
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: telemetry: config: optspec: {
+  # receives each finished span
+  exporter: '`$FUNCTION`'
+  # extra headers merged into the propagated context
+  headers: '`$MAP`'
+  # supplies trace and span ids
+  idgen: '`$FUNCTION`'
+  # injected clock
+  now: '`$FUNCTION`'
+}

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

@@ -30,3 +30,16 @@ main: kit: feature: test: {
 }
 
 
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: test: config: optspec: {
+  # seeded records, keyed by entity name
+  entity: '`$MAP`'
+  # netsim-shaped conditions for the mock transport
+  net: '`$MAP`'
+}

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

@@ -18,3 +18,18 @@ main: kit: feature: timeout: {
   # Timeout wraps the transport in init(); it dispatches no pipeline hooks.
   hook: {}
 }
+
+
+# TYPES for the options this feature reads but does not default.
+#
+# `config.options` is the defaults map — what happens when you say nothing —
+# so it can only describe an option that HAS a default. A callback has none,
+# and an option the caller either supplies or does not has none either. Left
+# undeclared these were invisible twice over: the generated option spec could
+# not type them, and the README's option table could not list them.
+main: kit: feature: timeout: config: optspec: {
+  # injected clearTimeout
+  clearTimer: '`$FUNCTION`'
+  # injected setTimeout
+  setTimer: '`$FUNCTION`'
+}

package/project/.sdk/model/feature/validate.aon

@@ -0,0 +1,73 @@
+
+main: kit: feature: validate: {
+
+  name: key()
+  title: "Payload validation against the model's own field types"
+  version: '0.0.1'
+  active: true
+  base: 'BASE'
+  transport: 'none'
+
+  # Applicability (docs/design/feature-tags.md): this feature is nothing
+  # without the generated `Schema` module, so it applies only to targets that
+  # emit one. ts and js today; a target joins by emitting Schema from its
+  # Main and declaring the tag.
+  needs: { schema: true }
+
+  # The one feature whose schema is not hand-written: the specs come from
+  # `fields[].type`, the canonical type sentinels apidef already records for
+  # every entity field and operation parameter, mapped into struct.validate's
+  # vocabulary at generation time (helpers/canonSpec) and emitted into the
+  # generated `Spec` module. Turning this on costs the model nothing extra;
+  # turning it off keeps those specs out of the generated source entirely.
+  config: {
+    options: {
+      active: false
+
+      # Check outbound payloads: what the caller asked to send, against the
+      # operation's request shape (the same partiality policy that decides
+      # what the generated `<Name>CreateData` type requires).
+      request: true
+
+      # Check inbound records against the entity's field types. OFF by
+      # default, and deliberately: a server that adds a field is not breaking
+      # its clients, and a spec built from a snapshot of the API would turn
+      # that into an error for every caller at once. Turn it on in tests and
+      # in staging, where an unannounced change is news rather than an
+      # outage.
+      response: false
+
+      # Reject keys the model does not declare. The generated specs are
+      # `$OPEN`, because apidef records the properties a spec declared and
+      # that is not a promise the payload carries nothing else; `strict`
+      # drops the `$OPEN` marker at init and closes them.
+      strict: false
+
+      # 'throw'  — a failure rejects the operation (a validate_failed error).
+      # 'report' — a failure is collected and the call proceeds.
+      mode: 'throw'
+    }
+
+    optspec: {
+      # A callback receiving every failure, whatever `mode` does with it, so
+      # a client can log or count invalid payloads without changing what the
+      # SDK returns. No default: it is supplied or it is not.
+      onInvalid: '`$FUNCTION`'
+
+      # CLOSED, unlike the default above. Read by example, `mode: 'throw'`
+      # is just "a string", and the runtime treats anything that is not
+      # 'report' as throw — so `mode: 'repot'` would have quietly kept
+      # enforcement on while its author believed they had turned it off.
+      # Naming the two values makes the typo a construction error.
+      mode: ['`$ONE`', ['`$EXACT`', 'throw'], ['`$EXACT`', 'report']]
+    }
+  }
+
+  hook: {
+    # Outbound, before the HTTP spec is built from the payload.
+    PreSpec: active: true
+
+    # Inbound, once the result data has been extracted from the response.
+    PreDone: active: true
+  }
+}

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

@@ -10,7 +10,7 @@ main: kit: target: js: {
   # Applicability (docs/design/feature-tags.md). A vendored sekreto port
   # lives in this target's feature container, so a feature that resolves
   # secrets through sekreto can apply here.
-  provides: { sekreto: true }
+  provides: { sekreto: true, schema: true }
 
   # Files earlier toolchains generated that this target has RETIRED
   # (vendor-tag rollout): the single fused runner. `doctor` reports

package/project/.sdk/model/target/ts.aon

@@ -10,7 +10,7 @@ main: kit: target: ts: {
   # Applicability (docs/design/feature-tags.md). A vendored sekreto port
   # lives in this target's feature container, so a feature that resolves
   # secrets through sekreto can apply here.
-  provides: { sekreto: true }
+  provides: { sekreto: true, schema: true }
 
   # Files earlier toolchains generated that this target has RETIRED
   # (vendor-tag rollout): the hand-written runner and the omni compat

package/project/.sdk/src/cmp/js/Main_js.ts

@@ -24,6 +24,7 @@ import {
 
 import { Package } from './Package_js'
 import { Config } from './Config_js'
+import { Schema } from './Schema_js'
 import { Gitignore } from './Gitignore_js'
 import { MainEntity } from './MainEntity_js'
 import { SdkError } from './SdkError_js'
@@ -193,6 +194,7 @@ if (fres instanceof Promise) { await fres }
     })
 
     Config({ target })
+    Schema({ target })
 
     EntityBase({ target })