@voxgig/sdkgen 4.20.0 → 4.22.0

package/project/.sdk/tm/ts/src/utility/MakePointUtility.ts

@@ -2,28 +2,6 @@
 import { Context, Point } from '../types'
 
 
-// The entity's OWN route among an op's points, as opposed to a
-// CROSS-REFERENCE: another resource's route that happens to return this
-// entity (`/notifications/{id}/board` for a board). Both are plain GETs
-// with no `$action`, so the path itself is all there is to go on.
-//
-// Two signals, in order:
-//
-//   1. A record route ends in the record's identifier (`/boards/{id}`,
-//      `/accounts/{account_id}/users/{id}`); a cross-reference ends in the
-//      relationship's name (`/posts/{id}/author`). A terminal parameter is
-//      therefore the stronger signal, and unlike depth it survives an entity
-//      nested more deeply than the route pointing at it.
-//   2. Failing that, fewest path segments — the shallower route is the one
-//      the entity is named for.
-//
-// Ties keep the earlier point, so the sorted-key order of the model decides
-// and the output stays byte-stable.
-//
-// The same rule runs at GENERATION time, in `shortestPoint`/`ownPoint` in
-// helpers/opShape.ts. It cannot be shared with this file — a template ships
-// standalone, outside that package — so it is written twice on purpose, and
-// both sides must move together.
 function terminalParam(point: any): boolean {
   const parts = point.parts
   const last = 0 < parts.length ? parts[parts.length - 1] : ''
@@ -109,19 +87,7 @@ function makePoint(ctx: Context): Point | Error {
       }
     }
 
-    // select.exist can list more than the params needed to pick a point (for
-    // /boards/{id} it is Trello's 17 optional query-includes), so a plain
-    // {id} call matches NOTHING. Fall back to the entity's OWN route rather
-    // than whichever point came last.
     if (!matched) {
-      // A request naming an action reaches here only because that action's
-      // own point failed its exist test, so the request is unbuildable
-      // whatever we pick. Refuse it BEFORE choosing a fallback: the guard
-      // below compares the chosen point's $action, and would wave the
-      // request through whenever the action point is itself the one the
-      // fallback selects (a short action route folded into an entity whose
-      // canonical route is longer). An unbuildable action request is an
-      // error, never a silent request to some other endpoint.
       if (null != reqselector.$action) {
         return ctx.error('point_action_invalid', 'Operation "' + op.name +
           '" action "' + reqselector.$action + '" is not valid.')

package/project/.sdk/tm/ts/src/utility/MakeRequestUtility.ts

@@ -36,7 +36,6 @@ async function makeRequest(ctx: Context): Promise<Response | Error> {
 
     spec.step = 'prerequest'
 
-    // TODO: see js code, use `native` prop here
     const fetched = await fetcher(ctx, fetchdef.url, fetchdef)
 
     if (null == fetched) {

package/project/.sdk/tm/ts/src/utility/MakeSpecUtility.ts

@@ -30,7 +30,6 @@ function makeSpec(ctx: Context): Spec | Error {
 
   ctx.spec.method = prepareMethod(ctx)
 
-  // TODO: Add string utils to StructUtility
   if (!options.allow.method.includes(ctx.spec.method)) {
     return ctx.error('spec_method_allow', 'Method "' + ctx.spec.method +
       '" not allowed by SDK option allow.method value: "' + options.allow.method + '"')
@@ -41,10 +40,6 @@ function makeSpec(ctx: Context): Spec | Error {
   ctx.spec.headers = prepareHeaders(ctx)
 
   if ('graphql' === (point as any).kind) {
-    // GraphQL addresses one endpoint: no path parts, no query string, and
-    // the body carries the operation. prepareBody is skipped deliberately —
-    // it only emits a body for data-input ops (create/update), whereas every
-    // GraphQL op posts one, including load/list/remove.
     ctx.spec.body = utility.graphqlBody(ctx)
     ctx.spec.path = ''
     // prepareQuery already copied the op's match arguments into the query

package/project/.sdk/tm/ts/src/utility/MakeUrlUtility.ts

@@ -23,7 +23,6 @@ function makeUrl(ctx: Context): Error | string {
   }
 
 
-  // TODO: use parts to avoid regexp?
   let url = join([spec.base, spec.prefix, spec.path, spec.suffix], '/', true)
   let resmatch: Record<string, any> = {}
 

package/project/.sdk/tm/ts/src/utility/ParamUtility.ts

@@ -1,13 +1,6 @@
 
 import { Context } from '../types'
 
-/* Find value of a match parameter, possibly using an alias.
- *
- * The match parameter may have an alias key. For example, the parameter `foo_id` may be
- * aliased to `id` in the entity data.
- *
- * This function returns `undefined` rather than failing.
- */
 function param(ctx: Context, paramdef: any) {
   const point = ctx.point
   const spec = ctx.spec
@@ -27,7 +20,6 @@ function param(ctx: Context, paramdef: any) {
 
   const pt = typify(paramdef)
 
-  // TODO: review this search algorithm
 
   const key = 0 < (T_string & pt) ? paramdef : getprop(paramdef, 'name')
 

package/project/.sdk/tm/ts/src/utility/PrepareBodyUtility.ts

@@ -14,9 +14,6 @@ function prepareBody(ctx: Context) {
     try {
       body = transformRequest(ctx)
 
-      // if (point.check.nobody && null == body) {
-      //   return error(ctx, new Error('Request body is empty.'))
-      // }
     }
     catch (err) {
       return error(ctx, err)

package/project/.sdk/tm/ts/src/utility/PrepareParamsUtility.ts

@@ -6,16 +6,12 @@ function prepareParams(ctx: Context) {
   const utility = ctx.utility
   const findparam = utility.param
 
-  // const struct = utility.struct
-  // const validate = struct.validate
 
   const point = ctx.point
 
   let params = point.args.params
-  // let reqmatch = ctx.reqmatch
 
   params = params || []
-  // reqmatch = reqmatch || {}
 
   let out: any = {}
   for (let pd of params) {
@@ -25,8 +21,6 @@ function prepareParams(ctx: Context) {
     }
   }
 
-  // TODO: review
-  // out = validate(out, point.validate.params)
 
   return out
 }

package/project/.sdk/tm/ts/src/utility/ResultBasicUtility.ts

@@ -14,7 +14,6 @@ function resultBasic(ctx: Context) {
     result.status = getprop(response, 'status', -1)
     result.statusText = getprop(response, 'statusText', 'no-status')
 
-    // TODO: use spec!
     if (400 <= result.status) {
       const msg = 'request: ' + result.status + ': ' + result.statusText
       if (result.err) {

package/project/.sdk/tm/ts/src/utility/StructUtility.ts

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/struct 0.3.4 (typescript/src/StructUtility.ts)
-// Source: https://github.com/voxgig/struct @ abd93227e3295151f8dcd18597c3f3f2577af8b7  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/struct @ 3110e839a3f35b2fbdb047bf0c24f29d144027ea  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE. */
 

package/project/.sdk/tm/ts/src/utility/TransformRequestUtility.ts

@@ -1,10 +1,6 @@
 
 import { Context } from '../types'
 
-/* Convert entity data or match query into a srtucture suitable for use as request data.
- *
- * The operation (op) property `reqform` is used to perform the data preparation.
- */
 function transformRequest(ctx: Context) {
   const spec = ctx.spec
   const utility = ctx.utility
@@ -31,22 +27,6 @@ function transformRequest(ctx: Context) {
 
 
 
-// `$action` selects WHICH POINT of the op to use (see MakePointUtility). It
-// is the SDK's own discriminator, never an API field, so it must not survive
-// into the wire body. The GraphQL path already strips it where it builds its
-// input object; this is the same rule on the REST path, which had no such
-// step and sent it verbatim -- `{"$action":"merge", ...}` to GitHub's merge
-// endpoint. Harmless there, because GitHub ignores unknown keys; not
-// harmless against an API that validates its request bodies strictly.
-//
-// Only a top-level key of a plain object: a body may legitimately be an
-// array or a scalar, and neither can carry a selector.
-//
-// `__proto__` is assigned through Object.defineProperty, never `body[key] =`.
-// It is a legal JSON key and can be a real API field, but plain assignment
-// invokes the inherited setter: the key would vanish from the serialised
-// request and silently become the body's prototype instead. Same treatment
-// as StructUtility's condenseSet, for the same reason.
 
 function stripAction(reqdata: any) {
   if (null == reqdata || 'object' !== typeof reqdata || Array.isArray(reqdata)) {

package/project/.sdk/tm/ts/src/utility/TransformResponseUtility.ts

@@ -2,10 +2,6 @@
 import { Context } from '../types'
 
 
-/* Convert data from respnse into a structure suitable for use as entity data.
- *
- * The operation (op) property `resform` is used to perform the data extraction.
- */
 function transformResponse(ctx: Context) {
   const spec = ctx.spec
   const result = ctx.result

package/project/.sdk/tm/ts/test/exists.test.ts

@@ -8,16 +8,6 @@ import { ProjectNameSDK } from '..'
 
 describe('exists', async () => {
 
-  // NOT async, and the assertion is deliberate.
-  //
-  // ProjectNameSDK.test() is synchronous — it returns the client, not a promise
-  // — so the `await` here was a no-op. Worse, it hid the weakness of the
-  // assertion: `null !== testsdk` is trivially true for ANY non-null value,
-  // including the promise an `await` would have unwrapped. The test could not
-  // have failed short of test() returning null.
-  //
-  // instanceof is the real check: it fails if test() ever starts returning a
-  // promise, or anything other than a client.
   test('test-mode', () => {
     const testsdk = ProjectNameSDK.test()
     equal(testsdk instanceof ProjectNameSDK, true,

package/project/.sdk/tm/ts/test/feature/Corpus.test.ts

@@ -1,20 +1,4 @@
 
-// Feature behaviour, driven by the SHARED corpus.
-//
-// This is the route PrimaryUtility.test.ts already takes for the utilities:
-// language-neutral cases in .sdk/test/test.json, executed against the REAL
-// generated SDK. Features here are ordinary classes in ordinary compiled
-// source, unit-tested the ordinary way — no transpiled templates, and no
-// miniature of the pipeline standing in for the pipeline (which is what
-// harness.ts does, and why its assertions can only be as right as the
-// miniature is). A feature is built through the generated config, wrapped
-// into a client built by the generated constructor, and driven by a real
-// entity operation. What is asserted is what ships.
-//
-// Everything in a case is data: features are activated by name, options are
-// plain JSON, the transport is scripted by `res`, and the assertion is a
-// subset of the client's own record. Turning `res` into a fetcher is the one
-// piece each language writes for itself.
 
 import { test, describe, before } from 'node:test'
 import { ok, deepStrictEqual } from 'node:assert'
@@ -25,12 +9,6 @@ import { join } from 'node:path'
 import { SDK, TEST_JSON_FILE } from '../utility/index'
 
 
-// Features with a corpus section — read from the corpus itself, so a
-// project-authored section (a custom feature added under
-// .sdk/test/feature/) runs without editing this file. Read eagerly: the
-// node test runner collects the per-feature tests at describe time,
-// before any `before` hook fires. An SDK generated without a listed
-// feature still skips, not fails.
 const FEATURES = Object.keys((() => {
   try {
     return JSON.parse(readFileSync(
@@ -86,14 +64,6 @@ function scriptedFetcher(res: any[]) {
 
 
 function makeClient(kase: any): any {
-  // `test: { active: true }` is the OPTION, not the `test` FEATURE.
-  //
-  // It says "this client is not live", which is what makes a REQUIRED
-  // OpenAPI server variable resolve to a deterministic `test-<name>`
-  // rather than refuse to construct (see makeOptions). It installs no
-  // transport, so the scripted fetcher below still stands — the FEATURE
-  // is transport: 'base' and would shadow it, which is why this cannot
-  // just turn the feature on.
   return new (SDK as any)({
     test: { active: true },
     feature: kase.feature,
@@ -102,13 +72,6 @@ function makeClient(kase: any): any {
 }
 
 
-// Every operation this SDK declares, in a stable order.
-//
-// The corpus cannot name an entity — it is shared by SDKs that have none in
-// common — so the runner finds them here. The generated client exposes one
-// capitalised, zero-argument accessor per entity, and the entity it returns
-// carries the same `name` the config is keyed by; that pairing is what turns
-// a config entry back into a callable method.
 function candidates(client: any): OpRef[] {
   const entities: Record<string, any> = client._rootctx.config.entity || {}
 
@@ -131,14 +94,6 @@ function candidates(client: any): OpRef[] {
     }
   }
 
-  // SAFE OPS FIRST. The corpus calls #OP1 repeatedly and reasons about what
-  // the transport did in between — a cache hit, a retry, a rate-limit wait.
-  // `load`/`list` are the GET ops, and the cache stores only successful GETs,
-  // so an SDK whose first usable op is a `create` (POST) can never satisfy
-  // "a hit served from cache costs nothing": nothing is ever cached, the
-  // second call goes to the network, and cost correctly charges twice. That
-  // reads as a cost defect and is not one. Ordering here rather than
-  // filtering keeps every SDK runnable, including ones with no GET at all.
   const SAFE: Record<string, number> = { list: 0, load: 1 }
   return out.sort((a, b) =>
     (SAFE[a.op] ?? 2) - (SAFE[b.op] ?? 2) || a.key.localeCompare(b.key))
@@ -223,17 +178,6 @@ describe('FeatureCorpus', () => {
   })
 
 
-  // A corpus with no `feature` section is a SKIP, not a failure.
-  //
-  // Each project carries its OWN materialised copy of .sdk/test/test.json, so
-  // a project scaffolded before the section existed legitimately has no cases
-  // to run - and a hard assertion here turned that into a red suite in every
-  // SDK on the fleet, for a corpus the project had simply not re-pulled yet.
-  //
-  // The strict check belongs where the corpus is CONTROLLED, not where it is
-  // consumed: sdkgen's own end-to-end lane generates against a corpus it
-  // supplies and requires the cases to actually run, so a section that goes
-  // missing there still fails loudly.
   test('the corpus carries a feature section', (t) => {
     if (null == corpus.feature) {
       return t.skip(

package/project/.sdk/tm/ts/test/feature/harness.ts

@@ -1,13 +1,4 @@
 
-// Offline feature-test harness for the generated SDK.
-//
-// Feature behaviour (retry, cache, rbac, telemetry, ...) is unit-tested by
-// driving each feature class through a faithful miniature of the real
-// operation pipeline against a configurable mock transport — the same hook
-// order and short-circuit rules as the generated Entity*Op code, but with
-// no live server and no API-specific fixtures. Feature instances are built
-// via `config.makeFeature`, so only features actually present in this SDK
-// are exercised (see `hasFeature`).
 
 import { config, stdutil } from '../..'
 

package/project/.sdk/tm/ts/test/feature/secrets/Secrets.test.ts

@@ -1,16 +1,3 @@
-// Behavioural tests for the secrets feature (vendored @voxgig/sekreto).
-//
-// The contract under test: the `apikey` OPTION keeps its exact old meaning
-// and always wins, because SecretsFeature places it FIRST in the provider
-// chain (a `memory` store named `options`) — explicit-beats-lookup falls
-// out of sekreto's first-hit rule rather than from special-case logic.
-// With the feature inactive nothing changes at all. With it active and the
-// option unset, the chain (env, dotenv, a custom provider, a vault)
-// supplies the credential instead.
-//
-// This file lives in the `feature/` container on purpose: `target add`
-// trims it, along with the feature source and the vendored library, for a
-// project whose model does not select `secrets`.
 
 import { test, describe, beforeEach } from 'node:test'
 import assert from 'node:assert'
@@ -32,12 +19,6 @@ async function prepared(sdkopts: any): Promise<any> {
 }
 
 
-// The Authorization header carries the SPEC's credential prefix, which a
-// TEMPLATE cannot know: an OpenAPI `http`/`bearer` scheme gives
-// `Bearer <token>`, an apiKey scheme the raw token. So assert on the
-// CREDENTIAL and let the prefix be whatever this SDK's API declares —
-// pinning the whole header value passes only for a prefix-less API, and
-// this file ships to every project that selects the feature.
 function credentialIs(header: any, token: string) {
   const got = String(null == header ? '' : header)
   assert.ok(got === token || got.endsWith(' ' + token),
@@ -93,12 +74,6 @@ describe('secrets', () => {
   })
 
 
-  // The three ways an apikey can be "not given", pinned together because
-  // they are easy to conflate and only one of them is a suppression.
-  //
-  // makeOptions normalises an omitted apikey to '' before features
-  // initialise, so by init time omitted and explicit-empty are
-  // indistinguishable — both defer to the chain, deliberately.
 
   test('active: an OMITTED apikey defers to the chain', async () => {
     process.env[ENVPREFIX + 'APIKEY'] = 'ENVKEY01'
@@ -115,21 +90,6 @@ describe('secrets', () => {
   })
 
 
-  // `auth: null` — the documented way to disable auth outright, which
-  // prepareAuth honours before it ever reads the apikey.
-  //
-  // This needs an explicit guard because struct 0.3.2 nearly removed it in
-  // silence. Under 0.0.10, getprop returned a stored null as null, so
-  // validate saw `auth: null` as a non-map and REJECTED it for any SDK
-  // whose optspec supplies an `auth` default. Under 0.3.2 getprop treats a
-  // stored null as "no value", so the default fires instead and the
-  // suppression became "use default auth" — transmitting a credential the
-  // caller explicitly asked not to send. makeOptions now captures
-  // suppliedness BEFORE validate and restores the null after it.
-  //
-  // No corpus entry could catch this: corpus nulls travel as the
-  // '__NULL__' string, so real-JSON-null semantics are invisible to every
-  // port's shared fixtures.
   test('active: auth null suppresses the credential, chain or no chain',
     async () => {
       process.env[ENVPREFIX + 'APIKEY'] = 'ENVKEY01'
@@ -177,13 +137,6 @@ describe('secrets', () => {
   })
 
 
-  // sekreto's miss-vs-error invariant: a MISS falls through to the next
-  // provider, an ERROR does not. A broken vault must never degrade into an
-  // unauthenticated request.
-  //
-  // On the DIRECT path the error is RETURNED, not thrown: _rawRequest
-  // awaits prepare() outside its try, and direct()/graphql() are documented
-  // to return a value or an Error and never reject.
   test('active: a provider ERROR is returned by prepare, not thrown',
     async () => {
       const sdk = (SDK as any).test({}, {
@@ -260,15 +213,6 @@ describe('secrets', () => {
   })
 
 
-  // A MISS IS NOT A CACHEABLE ANSWER — sekreto's own rule, which this
-  // feature used to override from the layer above.
-  //
-  // Default caching here, deliberately: `cache: true` is about holding a
-  // HIT, and holding the settled promise after a miss meant the chain was
-  // never asked again for the life of the client. A secret provisioned
-  // after startup (a mounted file, a vault policy granted a minute late)
-  // was invisible forever, and the only workaround was giving up hit
-  // caching entirely.
   test('active: a MISS is re-asked, so a late secret is picked up',
     async () => {
       let calls = 0
@@ -355,14 +299,6 @@ describe('secrets', () => {
   })
 
 
-  // The bridge that makes the whole design work: resolution is async, the
-  // auth header is built synchronously, and entity ops await
-  // featureHook('PreSpec') before makeSpec — so that is where the lookup
-  // happens and still lands in time.
-  //
-  // The entity is discovered from the SDK's own config rather than named,
-  // because this file is a TEMPLATE: it ships to every project, and no
-  // project's entity names are known here.
   test('active: entity ops resolve via the PreSpec hook', async () => {
     process.env[ENVPREFIX + 'APIKEY'] = 'ENVKEY02'
 
@@ -377,18 +313,6 @@ describe('secrets', () => {
     // Before any op, nothing has been resolved.
     assert.equal(sdk.options().apikey, '')
 
-    // AN OP THAT EXISTS, not `list` on whichever entity comes first.
-    //
-    // A generated TS entity carries only the ops its model DECLARES, so
-    // `list` is absent from an entity declaring `create` alone — and
-    // calling it throws before the PreSpec hook can run, failing the
-    // assertion below for a reason that has nothing to do with secrets.
-    // univec-sdk hit exactly that: its first entity declares `create`
-    // only, so this test failed on every run while PreSpec worked
-    // perfectly. Any real op exercises the hook; `list` is not special.
-    //
-    // This file is a TEMPLATE, so no project's op names are known here
-    // either. Discover the first callable one rather than assuming.
     let ran = false
     for (const one of names) {
       const acc = one.charAt(0).toUpperCase() + one.slice(1)
@@ -424,17 +348,6 @@ describe('secrets', () => {
 })
 
 
-// ACCESS-TOKEN EXCHANGE.
-//
-// The shape these tests pin: what the chain resolves is a REFRESH token,
-// which is POSTed to a token endpoint for a short-lived ACCESS token; the
-// access token is what the Authorization header carries; and when the API
-// answers 401 the client buys another and tries the same request again,
-// once.
-//
-// A LIVE client throughout, with `system.fetch` stubbed. Test mode is
-// deliberately excluded here — it buys nothing (see SecretsFeature._buy),
-// which is the subject of its own test at the end.
 describe('secrets exchange', () => {
 
   const BASE = 'http://exchange.test/api'
@@ -587,7 +500,6 @@ describe('secrets exchange', () => {
     assert.equal(stub.api().length, 2, 'expected the request to be retried')
 
     authIs(stub.api()[0], 'ACCESS01')
-    // The retry must carry the NEW token, not the spent one.
     authIs(stub.api()[1], 'ACCESS02')
 
     assert.equal(res.ok, true, 'the caller sees the successful retry')
@@ -749,10 +661,6 @@ describe('secrets exchange', () => {
   test('auth: null suppresses the credential, refusal or not', async () => {
     process.env[ENVPREFIX + 'REFRESH_TOKEN'] = REFRESH
 
-    // `auth: null` is the documented way to send no credential at all.
-    // A refusal of a deliberately unauthenticated request is not an
-    // expired token: buying one and retrying would transmit exactly the
-    // credential the caller suppressed.
     const stub = stubfetch({ apiStatus: [401] })
     const sdk = new (SDK as any)({
       base: BASE,
@@ -774,10 +682,6 @@ describe('secrets exchange', () => {
     assert.equal(stub.api()[0].auth, undefined,
       'no credential may be sent when auth is suppressed')
 
-    // AND NO PURCHASE. This is the half the API-call assertions cannot see:
-    // resolve() runs before _withRefresh's suppression check, so the
-    // refresh token used to go to the token endpoint in a request body
-    // even here. Stopping the retry does not unsend it.
     assert.equal(stub.token().length, 0,
       'auth: null suppressed the credential but the refresh token was ' +
       'still POSTed to the exchange endpoint')
@@ -787,16 +691,6 @@ describe('secrets exchange', () => {
   test('a token another request already bought is spent, not re-bought', async () => {
     process.env[ENVPREFIX + 'REFRESH_TOKEN'] = REFRESH
 
-    // STAGGERED 401s: the case the shared in-flight purchase does NOT
-    // cover. Two requests go out on the same token; the first is refused,
-    // buys a new one and clears the shared promise; only then is the
-    // second refused. Buying again there is a wasted exchange, and on a
-    // provider that invalidates the previous credential on issuance it
-    // breaks the first request's own retry.
-    //
-    // Driven through the transport wrapper directly, because the race is
-    // in WHEN the refusal arrives relative to another request's refresh,
-    // and that is not something two ordinary calls can be made to stage.
     const stub = stubfetch()
     const sdk = exchangeSdk(stub)
 

package/project/.sdk/tm/ts/test/live-contract.ts

@@ -1,7 +1,5 @@
 import { LiveBlocked } from './live-runner'
 
-// Deliberately conservative: unsupported constraints block preparation instead
-// of labelling an invented value as live-valid. Errors never include values.
 export function validateContract(schema: any, value: any, direction = 'request', depth = 0): void {
   const bad = () => { throw new Error('Operation contract mismatch') }
   if (depth > 40 || schema === false) return bad()

package/project/.sdk/tm/ts/test/omni.ts

@@ -1,27 +1,3 @@
-// The corpus test runner: vendored @voxgig/omni driven through its NATIVE
-// API (`makeRunner(specref, provider)`), presented to the corpus tests in
-// the struct-runner shape they already use (`R.spec`, `R.runset`,
-// `R.runsetflags`, `R.client`). No compat shim is vendored: the adapter
-// below IS the whole bridge, per language, per the vendor-tag rollout
-// (docs/design/vendor-tag-rollout.md, Decision 4).
-//
-// Two local decisions, both required:
-//
-// 1. SPEC PATH. omni's own spec resolution expects the caller to hand it a
-//    usable path — its docs say a port must resolve the path itself. This
-//    module compiles to dist-test/omni.js, the same depth as the old
-//    dist-test/runner.js, so the existing TEST_JSON_FILE constant keeps
-//    working verbatim: a relative path is absolutized against __dirname.
-//
-// 2. PROVIDER DELEGATION. Corpus-driven contexts get `ctx.client` set to
-//    the runner's provider (omni overwrites it on any ctx/args map entry).
-//    A five-hook provider object HIDES the live SDK from the generated
-//    utilities that reach through it — prepareHeaders via client.options(),
-//    fetcher via client._mode, the feature helpers via client._rootctx and
-//    even ASSIGNING client._features. So the provider here is built by
-//    PROTOTYPE DELEGATION over the live SDK instance: every SDK member
-//    resolves, while the omni hooks sit on top. (Upstream omni#56 tracks
-//    giving the stock provider the same shape.)
 
 import { isAbsolute, join } from 'node:path'
 
@@ -37,8 +13,6 @@ import {
 import type { Json, Provider, Subject } from './vendor/omni/index'
 
 
-// The runner API the corpus tests consume — struct's runner shape, name
-// for name, served over native omni.
 export type StructSubject = (...args: any[]) => any
 export type StructRunSet = (testspec: any, testsubject?: StructSubject) => Promise<void>
 export type StructRunSetFlags = (
@@ -67,11 +41,8 @@ export type StructProvider = Provider & {
 }
 
 
-// The omni hooks for an SDK subject — what the retired compat shim called
-// `structprovider`, inlined here because this resolver is the one consumer.
 function sdkhooks(sdk: any) {
   return {
-    // A subject is resolved from the utility, or from utility.struct.
     subject: (name: string): Subject | undefined => {
       const utility = sdk.utility()
       return utility[name] || (utility.struct && utility.struct[name])
@@ -81,7 +52,6 @@ function sdkhooks(sdk: any) {
     // same delegating shape, not a plain hook object.
     client: async (options: Json) => sdkprovider(await sdk.tester(options)),
 
-    // The SDK supplies its own context wrapper.
     contextify: (val: Json): Json => {
       const utility = sdk.utility()
       const hook =
@@ -95,7 +65,6 @@ function sdkhooks(sdk: any) {
       return ctx
     },
 
-    // Client options may reference the runner store.
     inject: (options: Json, store: Json): Json => {
       const structutils = sdk.utility().struct
       if (structutils && 'function' === typeof structutils.inject) {
@@ -144,7 +113,6 @@ async function makeRunner(testfile: string | Json, client: any): Promise<StructR
 }
 
 
-// struct's flag-modifier name, served from native omni.
 const nullModifier = nullmodifier