@voxgig/station 0.0.2 → 0.2.0

package/src/adapter.ts

@@ -1,34 +1,16 @@
 import { StationError } from './error'
 import { Station } from './Station'
 
-// The station side of the plugin contract (design §3), in ONE place:
-// featureBinding() is what both entry paths delegate to -
-//  - the GENERATED station feature (sdkgen-station's ts template) calls
-//    it from its init() and forwards its hook methods;
-//  - the library's carried adapter (adapterFeature, the adopt/connect
-//    retrofit for SDKs generated without the feature) is a thin shell
-//    over the same call.
-// Registration at init, wrap position verified, transport wrapped with
-// copy-on-inject, hooks bridged to op events. Anything changed here
-// changes both paths - which is the point.
 
 let corrSeq = 0
 
 export type FeatureBinding = {
-  // The INSTANCE name (§7.1). Keeps the field name so the generated
-  // adapter contract is unchanged; for a single-instance project it is
-  // the api slug, exactly as before.
   slug: string
   PrePoint(ctx: any): void
   PreDone(ctx: any): void
   PreUnexpected(ctx: any): void
 }
 
-// Resolve the station this activation binds to: an explicit handle in
-// the feature options (connect/adopt and st.options() pass one), else
-// the ambient instance. No station open -> null: an activated feature
-// with no opened station is an inert no-op that emits nothing and
-// fails nothing (design §3.1).
 export function featureBinding(ctx: any, fopts: any): FeatureBinding | null {
   const station: Station | null =
     (fopts?.station instanceof Station ? fopts.station : null) ?? Station.current()
@@ -36,18 +18,11 @@ export function featureBinding(ctx: any, fopts: any): FeatureBinding | null {
 
   const client = ctx.client
 
-  // Same construction, second arrival (generated feature + carried
-  // adapter both active on one client): the first bind won, this one
-  // is inert. See Station._boundEntry.
   if (null != station._boundEntry(client)) { return null }
   const utility = ctx.utility
   const options = ctx.options
   const calleropts = fopts?.calleropts
 
-  // Position guard (design §3.3): the wrap must sit immediately
-  // outside the base transport - inside retry/cache/ratelimit - or
-  // its http events stop being wire truth. Position in
-  // client._features IS init order, so verify it and fail loudly.
   const names = client._features.map((f: any) => f.name)
   const self = names.indexOf('station')
   const testAt = names.indexOf('test')
@@ -58,15 +33,8 @@ export function featureBinding(ctx: any, fopts: any): FeatureBinding | null {
       'feature order is [' + names.join(', ') + ']')
   }
 
-  // §7.5: registration is driven by station now. `fopts.instance` is
-  // where station puts the instance name it knew before construction
-  // began; `_register` reads it and falls back to the descriptor slug,
-  // which is today's behaviour for a bare connect(SDK).
   const reg = station._register(client, ctx.config, options, calleropts, fopts)
   const { binding, profilePlugin } = reg
-  // The INSTANCE name, not the api slug. Everything below keys on it -
-  // the placeholder, the transport seam, the op events - because two
-  // live instances of one api must be distinguishable at each.
   const name = binding.plugin
 
   // Base URL precedence (design §3.5): caller opts (7) beat the
@@ -78,18 +46,6 @@ export function featureBinding(ctx: any, fopts: any): FeatureBinding | null {
     options.base = profilePlugin.base
   }
 
-  // Policy allowlists (design §16): `allow.op` / `allow.method` are
-  // "the same vocabulary the SDKs already enforce (`options.allow`, and
-  // the raw-access gate every target implements); station sets these
-  // SDK options from policy so enforcement is in the SDK's own
-  // pipeline" - the point_op_allow / spec_method_allow gates. The SDK's
-  // own option form is a comma-separated string, so the policy's list
-  // joins into it. Applied at binding time, which is inside the
-  // constructor, and on BOTH entry paths - connect/adopt and the
-  // declarative build both delegate here. Unlike `base` above, which is
-  // a default the caller may override, an allowlist is ENFORCEMENT:
-  // policy wins over whatever the options carry, on exactly the keys it
-  // sets.
   const pallow = profilePlugin?.policy?.allow
   if (null != pallow && 'object' === typeof pallow) {
     const allow = {
@@ -104,10 +60,6 @@ export function featureBinding(ctx: any, fopts: any): FeatureBinding | null {
   if ('none' !== binding.rung) {
     const placeholder = binding.placeholder!
 
-    // A real credential already resident in the options is hoisted
-    // into the broker and replaced by the placeholder before
-    // construction completes (design §3.1 adopt) - options() and
-    // prepare() output become placeholder-safe from here on.
     const resident = options.apikey
     if ('string' === typeof resident && '' !== resident && placeholder !== resident) {
       station._hoist(name, resident)
@@ -115,9 +67,6 @@ export function featureBinding(ctx: any, fopts: any): FeatureBinding | null {
     options.apikey = placeholder
   }
 
-  // Wrap the transport. Copy-on-inject (design §5.3) happens inside
-  // station._transport; auth-inactive plugins skip credential
-  // planning but the wrap still observes (design §5.3).
   const inner = utility.fetcher
   if (true === (inner as any).__station__) {
     throw new StationError('station_bound_twice',
@@ -132,8 +81,6 @@ export function featureBinding(ctx: any, fopts: any): FeatureBinding | null {
   return {
     slug: name,
 
-    // Hook bridge (design §3 item 3): operation semantics correlated
-    // with the HTTP events via a per-operation id on the SDK's own ctx.
     PrePoint(opctx: any): void {
       opctx.station$ = { corr: 'c' + (++corrSeq), start: Date.now() }
     },
@@ -158,10 +105,6 @@ export function adapterFeature(station: Station, calleropts: any): any {
     active: true,
     _binding: null as FeatureBinding | null,
 
-    // featureAdd reads _options for positioning: immediately after the
-    // test feature's base transport (design §3.3). When test is absent
-    // from the add order this is a no-op append, which for a bare SDK
-    // still lands the wrap immediately outside the base transport.
     _options: { __after__: 'test' },
 
     init(ctx: any, fopts: any): void {

package/src/config-shape.ts

@@ -1,14 +1,3 @@
-/* MIRROR of `spec/config-shape.json` - design §4.3, verbatim.
- *
- * The JSON under `spec/` is the artifact every port reads; this module
- * is the TypeScript port's shipped copy of it. It exists because
- * `package.json` ships `dist/src` only, so a runtime read of `spec/`
- * works in the repo and breaks in a published consumer - and
- * `validateConfig` runs at `open()`, not just under test.
- *
- * DO NOT EDIT THIS FILE. Edit `spec/config-shape.json`, then re-run
- * `make sync-shape`. `test/shape.test.ts` fails on drift.
- */
 
 export const CONFIG_SHAPE: any = {
   "station": [

package/src/descriptor.ts

@@ -1,9 +1,5 @@
 import { Descriptor, DescriptorEntity, DescriptorPoint } from './types'
 
-// The ONLY way to build an env-var token in station, mirroring sdkgen's
-// packageMeta envToken exactly: 'gnarly-pets' -> 'GNARLY_PETS'. The
-// `secretname` corpus section pins the round-trip against sekreto's
-// envkey() and sdkgen's envName() - the one place three grammars meet.
 export function envtoken(name: any): string {
   return String(name || '')
     .toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
@@ -16,10 +12,6 @@ export function secretnameDefault(slug: string): string {
   return envtoken(slug).toLowerCase() + '.apikey'
 }
 
-// Best-effort slug from a camel name, for SDKs whose embedded config
-// predates main.slug (design §4 legacy sentinels). The hyphen caveat is
-// real: 'VoxgigSolardemo' -> 'voxgigsolardemo', NOT 'voxgig-solardemo' -
-// callers surface a warning event when this path is taken.
 function legacySlug(name: string): string {
   return String(name || '').toLowerCase()
 }
@@ -90,20 +82,6 @@ export function normalizeDescriptor(config: any, activeFeatures?: Record<string,
     entities[ename] = { fields, ops }
   }
 
-  // §7.4: the features list gains `options` and `transport`, because
-  // it was throwing away what the SDK already embeds -
-  // `config.feature[name].options` is the feature's own declared key
-  // set WITH TYPED DEFAULTS, which is the schema §8.5 validates
-  // against, and `transport` is the role §8.4 orders by.
-  //
-  // Both are already inside the SDK; the descriptor stops discarding
-  // them. ADDITIVE, so descriptor v1 consumers are unaffected.
-  //
-  // `transport` is carried rather than inferred: the obvious signal, an
-  // empty `hook: {}`, is wrong for station, which both wraps AND
-  // dispatches hooks. Absent until sdkgen emits it (§11 items 6-7), and
-  // §8.4's role checks degrade to nothing until then rather than
-  // guessing.
   const features: {
     name: string, active: boolean,
     options?: Record<string, any>, transport?: string,
@@ -134,19 +112,6 @@ export function normalizeDescriptor(config: any, activeFeatures?: Record<string,
   return { descriptor, warnings }
 }
 
-// Canonical serialization (design §4): UTF-8, object keys sorted
-// bytewise, no insignificant whitespace, minimal JSON escaping. The
-// proxy dedupes registrations by a hash of this, so every language must
-// produce identical bytes - the `canonical-serialize` corpus section
-// carries the adversarial cases.
-//
-// The bytewise sort compares UTF-8 BYTE SEQUENCES, not UTF-16 code
-// units, through TextEncoder rather than Buffer: TextEncoder is a
-// standard global in Node and every browser, so this module stays on
-// the browser entry's import graph (§2.2, §17 Phase 1) with no node:
-// dependency. Uint8Array elements are unsigned bytes, so plain numeric
-// comparison IS the bytewise order Buffer.compare gave - the corpus'
-// non-ASCII sort case pins the equivalence.
 const UTF8 = new TextEncoder()
 
 function bytecompare(a: string, b: string): number {
@@ -170,7 +135,6 @@ export function canonicalSerialize(value: any): string {
   }
   if ('object' === typeof value) {
     const keys = Object.keys(value).filter((k) => undefined !== value[k])
-    // Bytewise sort: compare UTF-8 byte sequences, not UTF-16 code units.
     keys.sort(bytecompare)
     return '{' + keys.map((k) =>
       JSON.stringify(k) + ':' + canonicalSerialize(value[k])).join(',') + '}'

package/src/error.ts

@@ -20,11 +20,6 @@ const CODES = [
   'station_open_conflict',
   'station_bound_twice',
 
-  // Declarative config (station-declarative-config.md §6.4). Stage 1
-  // raises the first three; `station_feature_reserved` is the pure-data
-  // half of §8.4/§8.6, checkable before feature.ts exists because both
-  // rules are lexical - a `station` key in a feature map, a `feature`
-  // key inside `options`.
   'station_config_invalid',
   'station_config_secret',
   'station_secret_collision',

package/src/factory.ts

@@ -1,31 +1,3 @@
-/* The factory table (design §6.2).
- *
- * A FACTORY IS A CONSTRUCTOR *PLUS* THE SDK'S STATIC CONFIG, not a bare
- * function, and leaving the second half out was a hole in the first
- * draft of §6.2.
- *
- * Station composes the ordered feature array FOR the constructor, so it
- * needs the transport roles and the feature option schemas BEFORE
- * construction — but §7.5 has the adapter build and register its
- * descriptor DURING construction. Nothing would be known in time.
- *
- * The config is available, though: `configDefinition` emits it as a
- * module-level constant in the generated package, so it exists as soon
- * as the package is linked and long before any instance is built.
- * Station normalizes the descriptor AT PROVIDE TIME, and three things
- * follow:
- *
- *  - §7.4's per-api descriptor cache is populated at registration
- *    rather than on first construction;
- *  - `check()` can validate every instance's feature config WITHOUT
- *    constructing anything;
- *  - the adapter's registration during construction becomes a
- *    reconciliation — same descriptor, now bound to a live client —
- *    rather than the first sighting.
- *
- * The table is PROCESS-GLOBAL because path 1 of §6.2 is module
- * self-registration: a generated package registers itself when it is
- * linked, which happens once per process and not once per Station. */
 
 import { StationError } from './error'
 import { normalizeDescriptor } from './descriptor'
@@ -45,13 +17,6 @@ export type FactoryEntry = {
 
 const TABLE = new Map<string, FactoryEntry>()
 
-/** Register an api's `{construct, config}` pair.
- *
- * Idempotent per api: registering the SAME pair twice is a no-op,
- * because module self-registration and an explicit `provide` for one
- * api is an ordinary thing for an application to end up with. A second
- * registration with a DIFFERENT factory is `station_factory_conflict` —
- * silently picking one of two SDK builds is not a thing to do quietly. */
 export function provide(api: string, factory: Factory): FactoryEntry {
   const slug = String(api)
   const prior = TABLE.get(slug)
@@ -86,8 +51,6 @@ export function provided(): string[] {
   return Array.from(TABLE.keys()).sort()
 }
 
-/** Test seam. The table is process-global by design, so a suite that
- * registers factories has to be able to put the process back. */
 export function resetFactories(): void {
   TABLE.clear()
 }

package/src/feature.ts

@@ -1,10 +1,3 @@
-/* Feature management (design §8): the three-level merge, the
- * constraint-and-band resolver, and the descriptor-derived checker.
- *
- * The resolver is written to voxgig/plugin's §7 semantics so plugin can
- * extract it — this is one of the pieces the joint plan means by
- * "station builds natively to plugin's semantics". Keeping the two
- * spellings identical is what C4 holds station to. */
 
 import { StationError } from './error'
 
@@ -12,31 +5,8 @@ import { StationError } from './error'
 // §8.3 — the merge
 // ---------------------------------------------------------------------
 
-/** Reserved on a feature entry: not options, and never passed through
- * to the SDK's own option map. */
 export const RESERVED_KEYS = ['active', 'order']
 
-/** The six sources, in §3.3's order extended by the profile level:
- *
- *   1 base.feature            4 overlay.feature
- *   2 base.api[<api>].feature 5 overlay.api[<api>].feature
- *   3 base.sdk[<ref>].feature 6 overlay.sdk[<ref>].feature
- *
- * PROFILE SPECIFICITY OUTRANKS BLOCK SPECIFICITY, and within a profile
- * the narrower block wins — the same principle as §3.3, one level down.
- *
- * `feature` is the ONE key where §3.3's shallow-per-key rule is wrong:
- * composition is the entire point, a fleet default plus a per-instance
- * tweak. So it is a TWO-LEVEL merge — per feature name, then per option
- * key — and no deeper. A map-valued option REPLACES wholesale, which is
- * what `{"$MERGE": {"deep": 2}}` states and what a port defaulting to a
- * deep merge would silently get wrong.
- *
- * Same defaults-after-merge rule as §3.3, one level down: an entry
- * mentioned at one level with only a tuning key must NOT synthesize
- * `active` and switch on a feature a broader level turned off. That is
- * the §3.3 defect one level down, and it is why the caller passes RAW
- * blocks here. */
 export function mergefeatures(sources: any[]): { [name: string]: any } {
   const out: { [name: string]: any } = {}
   for (const src of sources) {
@@ -44,15 +14,12 @@ export function mergefeatures(sources: any[]): { [name: string]: any } {
     for (const name of Object.keys(src)) {
       const entry = src[name]
       if (!ismap(entry)) { out[name] = entry; continue }
-      // Per option key, and NOT deeper.
       out[name] = { ...(ismap(out[name]) ? out[name] : {}), ...entry }
     }
   }
   return out
 }
 
-/** The six sources for one instance, in order. Assembled here rather
- * than at the call site so the order lives in exactly one place. */
 export function featuresources(
   base: any, overlay: any, api: string, ref: string
 ): any[] {
@@ -70,19 +37,10 @@ export function featuresources(
 // §8.4 — activation and order
 // ---------------------------------------------------------------------
 
-/** `test` substitutes the base transport, so it takes the innermost
- * band; `station` sits immediately outside it, pinned; everything else
- * is band 0, outside station.
- *
- * THE DEFAULT IS TODAY'S BEHAVIOUR EXPRESSED IN THE NEW MODEL rather
- * than as a special case: a project that writes no `order` anywhere
- * sees exactly today's nesting, and sdkgen's two `makeOptions` special
- * cases become two band values rather than two branches. */
 export const BAND_DEFAULT = 0
 export const BAND_STATION = 100
 export const BAND_TEST = 200
 
-/** Higher is further IN. */
 export function defaultband(name: string): number {
   if ('test' === name) { return BAND_TEST }
   if ('station' === name) { return BAND_STATION }
@@ -91,20 +49,6 @@ export function defaultband(name: string): number {
 
 export type Ordered = { name: string, band: number, entry: any }
 
-/** Resolve the activation order: constraints, then bands, then the
- * feature's position in the merged map.
- *
- * `before`/`after` take a feature name or a list of them and are
- * SATISFIED VACUOUSLY when the named feature is absent — `after: 'test'`
- * loads fine in a project with no test feature, which is sdkgen's
- * `__after__` behaviour kept rather than reinvented.
- *
- * Constraints beat bands; bands break ties no constraint decides;
- * remaining ties break by declaration position, so the result is a
- * stable topological sort with no alphabetical accident in it.
- *
- * Returns OUTERMOST FIRST, which is the array form the constructor
- * takes and the direction plugin's chain composes in. */
 export function resolveorder(merged: { [name: string]: any }): Ordered[] {
   const names = Object.keys(merged).filter((n) => active(merged[n]))
   const pos = new Map<string, number>()
@@ -117,7 +61,6 @@ export function resolveorder(merged: { [name: string]: any }): Ordered[] {
     band.set(n, b)
   }
 
-  // edges: from OUTER to INNER. `after: X` means "further in than X".
   const inner = new Map<string, Set<string>>()
   for (const n of names) { inner.set(n, new Set()) }
 
@@ -127,7 +70,6 @@ export function resolveorder(merged: { [name: string]: any }): Ordered[] {
   for (const n of names) {
     const o = ismap(merged[n]) ? merged[n].order : undefined
     if (!ismap(o)) { continue }
-    // Vacuous when absent: an unknown name is not an error here.
     for (const other of listof(o.after)) {
       if (inner.has(other)) { inner.get(other)!.add(n) }
     }
@@ -173,23 +115,11 @@ export function resolveorder(merged: { [name: string]: any }): Ordered[] {
   return out
 }
 
-/** A feature named in the config is one you are ASKING for, so an entry
- * with no `active` is active. */
 function active(entry: any): boolean {
   if (!ismap(entry)) { return false !== entry }
   return false !== entry.active
 }
 
-/** Station's own position is PINNED and not orderable (§8.4): an order
- * that moves `station` away from immediately-outside-the-base is
- * REJECTED, not honoured.
- *
- * The pin is `innermost`, and the spelling matters. A chain composes
- * with the FIRST binding outermost, so a pin written in sort terms —
- * "station first" — would place every other wrapper between the adapter
- * and the base: the exact inversion of the invariant, and one that
- * would leave station's wire-truth events observing the wrong boundary
- * while still looking ordered. */
 export function checkpin(ordered: Ordered[]): void {
   const i = ordered.findIndex((o) => 'station' === o.name)
   if (-1 === i) { return }
@@ -217,23 +147,6 @@ export type FeatureFault = {
   message: string
 }
 
-/** Check a merged feature map against the SDK'S OWN DECLARATION.
- *
- * The schema arrives with the FACTORY rather than with a live client
- * (§6.2), so this needs no construction and no network — which is what
- * lets `check()` run it for every instance in CI.
- *
- * Derived from the descriptor, never hand-written, so it cannot drift:
- * when a feature gains an option, the next regeneration teaches station
- * about it with no station change.
- *
- * SCALARS AGREE BY CONSTRUCTION; COMPOUND OPTIONS ARE KIND-CHECKED, and
- * that limit is real. An empty list default says nothing reliable about
- * its element type and a nested map default says nothing about its
- * value shapes, so `methods: [{}]` against a `['GET']` default is
- * caught while `noProxy: []` accepts anything list-shaped. Closing that
- * needs the feature model to declare an explicit option schema rather
- * than only a default. */
 export function checkfeatures(
   merged: { [name: string]: any }, descriptor: any
 ): FeatureFault[] {

package/src/index.ts

@@ -1,18 +1,5 @@
-// @voxgig/station - one control surface for outbound integrations.
-//
-// THE NODE ENTRY. `index.browser.ts` is the browser condition's entry
-// (§2.2, §17 Phase 1): same surface MINUS the file-loading half
-// (loadConfig/findConfigFile/configScope) and this registration, which
-// is what hands Station the node-only file half without Station itself
-// importing a `node:` module.
 
-import { configScope, loadConfig } from './profile'
-import { setConfigFileIO } from './Station'
-
-setConfigFileIO({ loadConfig, configScope })
-
-export { Station, instanceRef, setConfigFileIO } from './Station'
-export type { ConfigFileIO } from './Station'
+export { Station, instanceRef } from './Station'
 export { provide, factoryFor, provided, resetFactories } from './factory'
 export type { Factory, FactoryEntry } from './factory'
 export {

package/src/loader.ts

@@ -1,43 +1,9 @@
-/* The loader (design §6.3), where the language allows it.
- *
- * In ts, js, py, rb, php, perl, lua, elixir and clojure a module can be
- * imported by name at runtime, so `api.<slug>.package` closes the loop:
- * station imports the package (which triggers self-registration, §6.2
- * path 1) and then looks up the factory.
- *
- * `sdk()` IS SYNCHRONOUS, AND IN TS/JS THAT BOUNDS WHAT THE LOADER CAN
- * IMPORT. A CommonJS package loads synchronously through `require`; an
- * ESM-only package only loads through `import()`, which is a promise.
- * Making `sdk()` async to cover that would put an `await` in front of
- * every call site in every language for a cost only two of them pay.
- * So the rule is explicit rather than discovered at runtime:
- *
- *  - the synchronous loader handles CommonJS, which is every SDK sdkgen
- *    generates (the ts target is `"type": "commonjs"`);
- *  - ESM packages load through an explicit `await station.load()`
- *    preload, after which `sdk()` is synchronous again for everything —
- *    one `await` at startup rather than one per call site;
- *  - a package only `import()` can load, reached through `sdk()`
- *    without a preload, is `station_sdk_load` WITH THE REMEDY IN THE
- *    MESSAGE. Never a silent half-loaded client.
- *
- * THIS IS A CODE-LOADING SURFACE DRIVEN BY A CONFIG FILE, so it has
- * rules, and they are enforced here rather than documented and hoped
- * for. See `checkPackage` and the `repoScoped` argument. */
 
 import { StationError } from './error'
 import { Factory, factoryFor, provide } from './factory'
 
-/** The fixed alias every generated package exports.
- *
- * `export` defaults to this rather than to a derived class name because
- * it is the same identifier in every generated package, where
- * `camelify(slug) + 'SDK'` is a rule that has to be recomputed and can
- * be wrong. The derived name is the SECOND attempt and an explicit
- * `export` the third. */
 export const DEFAULT_EXPORT = 'SDK'
 
-/** `stripe-eu` -> `StripeEu`, for the second-attempt export name. */
 export function camelify(slug: string): string {
   return String(slug).split(/[^A-Za-z0-9]+/).filter((s) => '' !== s)
     .map((s) => s[0].toUpperCase() + s.slice(1))
@@ -51,13 +17,6 @@ export function camelify(slug: string): string {
  * name. */
 export function checkPackage(api: string, pkg: string): string {
   const p = String(pkg)
-  // A TRAVERSAL SEGMENT IS NOT A LEADING MARKER, and checking only the
-  // first character missed it: `pkg/../../escape` starts with neither
-  // `.` nor `/`, so it passed — and node resolves it through
-  // `node_modules/pkg/../../escape`, importing application-local code
-  // from outside the named dependency. The whole point of this function
-  // is that a configured package stays inside the dependency graph a
-  // reviewer can see.
   const seg = p.split('/').some((x) => '.' === x || '..' === x)
   const bad =
     '' === p ||
@@ -75,10 +34,6 @@ export function checkPackage(api: string, pkg: string): string {
   return p
 }
 
-/** Build a `{construct, config}` pair from a module that self-registered
- * nothing — the retrofit path for a package whose SDK predates the
- * station feature. It is not descriptor-blind: a generated main module
- * exports its constructor AND the `config` singleton beside it. */
 export function factoryFromModule(
   api: string, mod: any, exportName?: string
 ): Factory {
@@ -124,8 +79,6 @@ export function loadSync(api: string, pkg: string, exportName?: string): boolean
     mod = require(pkg)
   }
   catch (e: any) {
-    // ERR_REQUIRE_ESM is the case the preload exists for, and the
-    // message has to name the remedy rather than the symptom.
     const code = String(e?.code || '')
     if ('ERR_REQUIRE_ESM' === code) {
       throw new StationError('station_sdk_load',
@@ -138,30 +91,12 @@ export function loadSync(api: string, pkg: string, exportName?: string): boolean
       String(e?.message || e))
   }
 
-  // Path 1: the module self-registered while being imported.
   if (null != factoryFor(api)) { return true }
 
   provide(api, factoryFromModule(api, mod, exportName))
   return true
 }
 
-/** The ESM preload behind `await station.load()`. Imports the package
- * and fills the SAME table the synchronous path fills. */
-/** A dynamic `import()` that SURVIVES THE COMMONJS EMIT.
- *
- * This package compiles with `module: "commonjs"`, and TypeScript
- * rewrites a literal `import(pkg)` into a promise around `require(pkg)`
- * — so `await station.load()` threw `ERR_REQUIRE_ESM` for exactly the
- * ESM-only packages it exists to preload, leaving no working path to
- * those SDKs at all. Verified against the emitted `dist/src/loader.js`,
- * which read `mod = require(pkg)`.
- *
- * `new Function` is the seam the compiler does not look inside. It is
- * deliberately the only one in this file, and it takes no caller input:
- * `pkg` has already been through `checkPackage`, and the body is a
- * constant. Changing the package to `module: "node16"` would fix it
- * more cleanly and is a whole-package decision rather than a defect
- * fix. */
 export const nativeImport: (p: string) => Promise<any> =
   new Function('p', 'return import(p)') as any
 
@@ -181,7 +116,6 @@ export async function loadAsync(
 
   if (null != factoryFor(api)) { return true }
 
-  // An ESM namespace puts a CommonJS module's exports under `default`.
   const flat = null != mod?.default && null == mod?.config ? mod.default : mod
   provide(api, factoryFromModule(api, flat, exportName))
   return true