@voxgig/station 0.1.0 → 0.2.0

package/dist/src/Station.js

@@ -18,24 +18,6 @@ const secrets_1 = require("./secrets");
 // in-process with no other component running. The proxy (D2) is a
 // deferred amplifier - `require` therefore fails on the operation path
 // (design §2.1/§14), and `auto` degrades to solo with one warning event.
-/** §6.1: `as` IS A TAG, NOT A FREE NAME.
- *
- * The api comes from the SDK being passed, so the resulting ref is
- * `<api>$<tag>` and multi-instance works imperatively too. A full ref is
- * also accepted and is VALIDATED: its name must equal the SDK's api
- * slug, or it is `station_instance_api`.
- *
- * Both forms are needed because the imperative path is where the api is
- * implicit in an argument rather than written in a key. An `as` that
- * took an arbitrary name would reintroduce exactly the second-identity
- * problem the ref re-key removed: under the ref invariant
- * `as: 'solar-eu'` would denote the untagged `solar-eu` DEFINITION, not
- * an instance of the SDK just handed in, and registry grouping, api
- * defaults and every ref consumer would disagree about what it is.
- *
- * A bare connect(SDK) with no name falls back to the descriptor slug,
- * which is today's behaviour and why the single-instance case is
- * unchanged to the byte. */
 function instanceRef(api, fopts) {
     const explicit = firstNonEmpty(fopts?.instance);
     if (null != explicit) {
@@ -51,30 +33,8 @@ function instanceRef(api, fopts) {
         }
         return api;
     }
-    // A full ref is validated against the api; a `$`-less string is a TAG
-    // and is joined to it.
-    //
-    // §6.1 gives both branches and does not say how to disambiguate a
-    // `$`-less string, which is a real ambiguity because a bare name is
-    // itself a valid (untagged) ref: `as: 'stripe'` on api `stripe` could
-    // read as the untagged ref `stripe` or as tag `stripe`. It is read as
-    // a TAG, giving `stripe$stripe`, because §6.1 says twice and
-    // emphatically that `as` is a tag rather than a free name, and a rule
-    // with no exceptions is the one that ports the same way twenty times.
-    // The alternative - collapsing when the tag happens to equal the api -
-    // is a special case that would make `as` mean different things at
-    // different values. Someone who wants the untagged instance passes no
-    // `as` at all, which is the documented spelling for it.
     return checkref(-1 === as.indexOf('$') ? api + '$' + as : checkapi(api, as));
 }
-// The ref grammar is the JOINT identity model's (station-and-plugin.md
-// §2, plugin design §4): a name is a package-ish specifier
-// (`^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`), a tag is not (`^[a-zA-Z0-9.~_-]+$`
-// or empty - it MAY start with a digit because auto-tagging assigns
-// integer tags, and admits neither `@` nor `/`); both cap at 1024; the
-// split is on the FIRST `$`, so `a$b$c` is a good name with a bad tag.
-// Discharges the C4 divergence rows that pinned instanceRef accepting
-// what plugin's grammar rejects.
 const REF_NAME_RE = /^[a-zA-Z@][a-zA-Z0-9.~_\-\/]*$/;
 const REF_TAG_RE = /^[a-zA-Z0-9.~_-]+$/;
 const REF_MAX = 1024;
@@ -91,8 +51,6 @@ function checkInstanceTag(tag) {
     if ('string' !== typeof tag) {
         return false;
     }
-    // The empty tag is an ordinary tag: the single-instance case writes
-    // no tag and never learns tags exist.
     if (0 === tag.length) {
         return true;
     }
@@ -126,14 +84,6 @@ function checkapi(api, ref) {
     return ref;
 }
 class Station {
-    /** §6.2's second path, and the front door the docs name.
-     *
-     * The package exported only the free `provide()` and the class had no
-     * static — so the documented `Station.provide(...)` call failed, and
-     * so did the remediation `station_no_factory` prints, which tells the
-     * user to make exactly that call. Delegates to the same
-     * process-global table the free function fills; there is one
-     * registry, not two. */
     static provide(api, factory) {
         (0, factory_1.provide)(api, factory);
     }
@@ -161,14 +111,12 @@ class Station {
     static current() {
         return Station.ambient;
     }
-    // Test seam: drop the ambient instance.
     static reset() {
         Station.ambient = null;
         Station.ambientOpts = null;
     }
     constructor(opts) {
         this.registry = new Map();
-        // §6.1: `sdk(name)` caches; `create()` deliberately does not.
         this.clients = new Map();
         // The raw config, kept for §8.7's provenance: the resolved profile
         // has already collapsed the levels that provenance has to name.
@@ -180,43 +128,15 @@ class Station {
          * registration. */
         this.aliasOf = new Map();
         this.closed = false;
-        // §7.4: THE DESCRIPTOR IS SHARED, because it describes the api rather
-        // than any use of it. `normalizeDescriptor` runs once per api and
-        // every instance of that api holds a reference to the same object - at
-        // 26 instances over 20 apis that is 20 normalizations, not 26, and the
-        // canonical serialization the proxy dedupes registrations by is
-        // computed once per api too.
-        //
-        // Keyed by the slug the config carries, which is available before
-        // normalization only from the config itself, so the miss path
-        // normalizes and then keys on the result.
         this.descriptorCache = new Map();
         this.opts = opts || {};
         const config = undefined !== this.opts.config
             ? this.opts.config
             : (0, profile_1.loadConfig)(this.opts.folder);
-        // §6.3: an in-code config is repo-scoped by construction - the
-        // application wrote it. A file is repo-scoped unless it came from
-        // ~/.voxgig/station.json.
-        // Explicit wins, then an in-code config (the application wrote it,
-        // so it is repo-scoped by construction), then where the file was
-        // found. Inferring BEFORE reading the explicit option was a real
-        // precedence bug: it made `repoScoped: false` unsettable for any
-        // caller passing a config in code, which is every test of the rule.
         this.repoScoped = this.opts.repoScoped
             ?? (undefined !== this.opts.config
                 ? true
                 : 'user' !== (0, profile_1.configScope)(this.opts.folder));
-        // Normalize, then validate (design §4.2). A malformed station.json
-        // fails open() with EVERY error at once - an eighteen-instance
-        // config must not die because the eighteenth has a typo'd package
-        // name.
-        //
-        // resolveProfile then reads the RAW config, NOT the normalized one.
-        // The normalized form is an input to validation and to nothing
-        // else: block defaults synthesized before the profile merge would
-        // let a one-key overlay overwrite the base's `active: false` and
-        // silently re-enable a barred integration (§3.3, §4.2).
         if (null != config) {
             (0, shape_1.validateConfig)((0, shape_1.normalizeConfig)(config));
         }
@@ -235,7 +155,6 @@ class Station {
             });
         }
     }
-    // --- binding forms (design §3.1) ---
     // connect(SDK, opts): station constructs the SDK itself, activating
     // the adapter with §3.3 ordering. The activation entry plus the
     // extend-supplied instance ride the tolerance added to the generated
@@ -254,35 +173,26 @@ class Station {
             throw new error_1.StationError('station_no_plugin', 'station is closed');
         }
         opts = opts || {};
-        const fmap = { ...(opts.feature || {}) };
+        const { as, instance, ...sdkopts } = opts;
+        const fmap = { ...(sdkopts.feature || {}) };
         fmap['station'] = {
             ...(fmap['station'] || {}),
             active: true, station: this, calleropts: opts,
-            // §6.1: `as` is a TAG, resolved against the api in _register -
-            // the api comes from the SDK being passed and is not knowable
-            // here until that SDK's config has been normalized.
-            ...(null == opts.as ? {} : { as: opts.as }),
-            ...(null == opts.instance ? {} : { instance: opts.instance }),
+            // §6.1: `as` is a tag, resolved against the SDK's api in _register.
+            ...(null == as ? {} : { as }),
+            ...(null == instance ? {} : { instance }),
         };
         const options = {
-            ...opts,
+            ...sdkopts,
             feature: fmap,
             // The carried adapter rides extend for SDKs generated WITHOUT
             // the station feature; when the generated class exists the
             // constructor uses it and the extend copy is skipped by name
             // (both delegate to featureBinding, so behavior is identical).
-            extend: [...(opts.extend || []), (0, adapter_1.adapterFeature)(this, opts)],
+            extend: [...(sdkopts.extend || []), (0, adapter_1.adapterFeature)(this, opts)],
         };
         return new SDK(options);
     }
-    // Inverted binding (design §3.1): build the plain options map a
-    // generated constructor already accepts - the handle, the activation
-    // entry, and the profile's per-plugin base (applied here, at
-    // options-build time, so caller opts passed in `extra` still win).
-    // §6.1: `options(instanceName?, extra?)`. The name is optional and
-    // leading, so every existing `options({...})` call is unchanged - the
-    // inverted binding is the static languages' path and they need to say
-    // which instance they are building without a second method.
     options(a, b) {
         const named = 'string' === typeof a;
         const instance = named ? a : undefined;
@@ -295,14 +205,6 @@ class Station {
         };
         return { ...extra, feature: fmap };
     }
-    // --- registration (design §3 item 1, called by the adapter) ---
-    // The registry entry whose client IS this object, or null. Used by
-    // featureBinding for idempotency: connect/adopt activate the station
-    // entry AND ride the carried adapter on extend, so on an SDK whose
-    // generated config carries a real station feature class the same
-    // construction reaches featureBinding twice - the second arrival
-    // must no-op, while a genuinely second client of the same SDK class
-    // still fails _register's slug check (§10.2).
     _boundEntry(client) {
         for (const entry of this.registry.values()) {
             if (entry.client === client) {
@@ -311,29 +213,10 @@ class Station {
         }
         return null;
     }
-    /** The profile block that governs an instance — its own if the
-     * profile declares it, otherwise its **api's**.
-     *
-     * `resolveProfile` builds `profile.sdk` from the declared refs alone
-     * ("an api block declares no instance, so the ref set comes from the
-     * two `sdk` maps"), shallow-merging `profile.api[a]` into each. That
-     * is right for a declared instance and leaves an IMPERATIVE one —
-     * `connect(SDK, { as: 'test' })`, named but never written into
-     * config — with no block at all. The api-level `secret`, `base` and
-     * most seriously `policy.hosts` then did not reach it, so a profile
-     * that denies egress everywhere denied nothing for a tagged client.
-     *
-     * ONE RULE, ONE PLACE: registration and the transport seam both ask
-     * here, because they disagreeing is how the credential and the
-     * allowlist came apart in the first place. */
     blockFor(name) {
         return this.profile.sdk[this.declaredRef(name)] ??
             this.profile.api[(0, profile_1.refapi)(name)];
     }
-    /** The DECLARED instance an assigned tag stands for, or the name
-     * itself. `create('stripe$prod')` registers under `stripe$1`, and
-     * every question about that client's configuration — its secret, its
-     * base, its egress policy — is a question about `stripe$prod`. */
     declaredRef(name) {
         return this.aliasOf.get(name) ?? name;
     }
@@ -345,45 +228,17 @@ class Station {
         // with no name falls back to the descriptor slug, which is today's
         // behaviour and why the single-instance case is unchanged.
         const name = instanceRef(api, fopts);
-        // §7.1: the check moves to the instance key. Two clients of one api
-        // is the NORMAL case now; two bindings of one instance is still the
-        // error it was.
         if (this.registry.has(name)) {
             throw new error_1.StationError('station_bound_twice', 'instance "' + name + '" is already registered; binding one client ' +
                 'twice is an error (§10.2)');
         }
         const profilePlugin = this.blockFor(name);
-        // Secret name precedence: the feature option (in-code, design §9
-        // config.options.secret) beats the profile, which beats the
-        // INSTANCE-derived default.
-        //
-        // §5.1: `secretnameDefault` takes the instance name, not the slug.
-        // For an untagged instance the two are the same string, so the
-        // single-instance case is unchanged to the byte - `voxgig-solardemo`
-        // still derives `voxgig_solardemo.apikey` and still reads
-        // VOXGIG_SOLARDEMO_APIKEY. `stripe$test` derives
-        // `stripe_test.apikey`, because each instance IS a separate
-        // credentialed use of the API.
-        //
-        // The descriptor's own `auth.secretname` stays the API-level
-        // default and is NOT used here (§7.4): one descriptor is shared by
-        // every instance of an api and cannot hold two instance-derived
-        // names, so whichever instance built the cached copy would report
-        // the other's secret metadata wrongly. This is the authority; that
-        // field is documentation.
-        // ...and the DEFAULT takes the declared name too, not the assigned
-        // tag: `stripe$1` created from `stripe$test` derives
-        // `stripe_test.apikey`, so every per-request client of one instance
-        // shares one broker cache entry (§5.3).
         const secretname = firstNonEmpty(fopts?.secret, profilePlugin?.secret) ||
             (0, descriptor_1.secretnameDefault)(this.declaredRef(name));
         const rung = descriptor.auth.active ? 'R1' : 'none';
         const binding = {
             plugin: name,
             instance: api,
-            // §7.2: two live instances of one api MUST have distinct
-            // placeholders or the injection seam cannot tell which credential
-            // a header wants.
             placeholder: descriptor.auth.active ? (0, secrets_1.placeholderFor)(name) : undefined,
             secretname: descriptor.auth.active ? secretname : undefined,
             rung,
@@ -404,22 +259,6 @@ class Station {
         });
         return { binding, profilePlugin };
     }
-    /** The descriptor describes the API, and is SHARED by every instance
-     * of it — which is §7.4's own reasoning for why the effective secret
-     * name moved to `Binding` and is not read off the descriptor.
-     *
-     * The same argument applies to feature activation, and this did not
-     * follow it: the cache is keyed by slug alone while
-     * `normalizeDescriptor`'s second argument decides each feature row's
-     * `active`. So two instances of one api constructed with different
-     * feature maps shared the FIRST one's feature state, and
-     * `descriptorOf()` / `canonicalDescriptor()` became
-     * construction-order-dependent.
-     *
-     * Normalized with no per-instance features, so the shared value holds
-     * only API-stable metadata — which is what `factory.ts` already does
-     * when it normalizes at provide time. Per-instance activation is
-     * `featuresOf(name)`'s answer, and always was. */
     describe(config, _feature) {
         const slug = String(config?.main?.slug ?? '');
         if ('' !== slug) {
@@ -443,7 +282,6 @@ class Station {
             },
         });
     }
-    // --- the transport middleware (design §3.3, §5.3) ---
     async _transport(name, inner, fctx, fullurl, fetchdef) {
         // Fail-closed means traffic (§2.1): with the proxy deferred,
         // `require` can never attach, so every operation fails here - the
@@ -457,20 +295,6 @@ class Station {
         const placeholder = (0, secrets_1.placeholderFor)(name);
         const live = 'live' === fctx.client._mode;
         const profilePlugin = this.blockFor(name);
-        // Policy mode (design §16): `live` is the default; `block` is the
-        // kill switch and refuses live egress outright. Enforced at the
-        // same seam as the hosts allowlist, and like it only on LIVE
-        // traffic - a test-mode client's mock transport is not egress.
-        //
-        // §14 names no mode-specific code, so `block` raises
-        // `station_host_allow` - the closest existing catalog code: the
-        // same `_allow` gate grammar, the same seam, the same meaning
-        // (egress denied by this plugin's policy), with the message naming
-        // the mode. `record`/`replay`/`mock` are proxy-era modes accepted
-        // by the grammar now (so a config written for the proxy is not a
-        // validation error) and fail `station_no_proxy` on the operation
-        // path until a proxy is attached - the same fail-closed behaviour
-        // `require` shows above.
         const mode = profilePlugin?.policy?.mode ?? 'live';
         if ('live' !== mode && live) {
             const err = 'block' === mode
@@ -481,12 +305,6 @@ class Station {
             this.emitErr(name, fctx, err);
             return err;
         }
-        // Egress policy (design §16), solo half: the hosts allowlist is
-        // enforced at the seam every request crosses. When a policy is
-        // present, redirects come back manual - a 3xx is a response like
-        // any other, so a Location off the allowlist cannot pull an
-        // automatic credentialed follow-up to an unapproved host (§8.2's
-        // rule, applied at the library seam).
         const hosts = profilePlugin?.policy?.hosts;
         if (null != hosts && live) {
             let hostname = '';
@@ -502,6 +320,8 @@ class Station {
             }
         }
         let senddef = fetchdef;
+        let sendurl = fullurl;
+        let placed = false;
         if (null != hosts && live) {
             senddef = { ...senddef, redirect: 'manual' };
         }
@@ -511,20 +331,6 @@ class Station {
         // enter in-memory mock stores. Copy-on-inject: the object graph
         // reachable from ctx/spec/ctrl keeps the placeholder, ever (§5.3).
         if (live && null != entry && 'R1' === entry.rung) {
-            // §7.4: THE EFFECTIVE NAME, resolved once at registration and
-            // stored on the entry. Re-deriving it here got the precedence
-            // right and the FALLBACK wrong: `descriptor.auth.secretname` is
-            // the API-level default, and one descriptor is shared by every
-            // instance of an api — so a tagged instance with no explicit
-            // `secret` read `stripe.apikey` where registration had recorded
-            // `stripe_test.apikey`. Either the request fails despite the
-            // credential being configured, or it succeeds with a sibling's.
-            //
-            // No fallback, and the `!` is the invariant rather than a shrug:
-            // this branch is guarded by `'R1' === entry.rung`, which is set
-            // only when `descriptor.auth.active` — the same condition under
-            // which `entry.secretname` is populated. Substituting a different
-            // name when it is absent is the bug above, written again.
             const secretname = entry.secretname;
             let value;
             try {
@@ -534,29 +340,30 @@ class Station {
                 this.emitErr(name, fctx, e);
                 return e instanceof Error ? e : new Error(String(e));
             }
-            senddef = { ...senddef, headers: { ...(senddef.headers || {}) } };
-            for (const h of Object.keys(senddef.headers)) {
-                const v = senddef.headers[h];
-                if ('string' === typeof v && v.includes(placeholder)) {
-                    senddef.headers[h] = v.split(placeholder).join(value);
-                }
+            const sent = (0, secrets_1.substitute)(fullurl, senddef.headers, placeholder, value);
+            sendurl = sent.url;
+            senddef = { ...senddef, headers: sent.headers };
+            const defurl = senddef.url;
+            if ('string' === typeof defurl) {
+                senddef.url = (0, secrets_1.substitute)(defurl, null, placeholder, value).url;
             }
+            placed = sendurl !== fullurl || senddef.url !== defurl;
         }
         const corr = fctx.station$?.corr;
         const started = Date.now();
         let res;
         try {
-            res = await inner(fctx, fullurl, senddef);
+            res = await inner(fctx, sendurl, senddef);
         }
         catch (e) {
             this.emitHttp(name, corr, fullurl, senddef, 0, started, 0);
             this.emitErr(name, fctx, e);
-            throw e;
+            throw this.scrubbed(e, placed);
         }
         if (res instanceof Error) {
             this.emitHttp(name, corr, fullurl, senddef, 0, started, 0);
             this.emitErr(name, fctx, res);
-            return res;
+            return this.scrubbed(res, placed);
         }
         let bytes = 0;
         const cl = res?.headers?.get?.('content-length');
@@ -566,6 +373,13 @@ class Station {
         this.emitHttp(name, corr, fullurl, senddef, res?.status || 0, started, bytes);
         return res;
     }
+    // A transport error may quote its URL, which carries a query-placed value.
+    scrubbed(err, placed) {
+        if (placed && err instanceof Error) {
+            err.message = this.redact(err.message);
+        }
+        return err;
+    }
     emitHttp(slug, corr, fullurl, fetchdef, status, started, bytes) {
         let host = '', path = '';
         try {
@@ -586,12 +400,6 @@ class Station {
     }
     emitErr(name, fctx, err) {
         this.emit({
-            // §7.3's grouping contract: `plugin` is the INSTANCE and `api` is
-            // what groups its siblings. Construction events carried both and
-            // the runtime ones did not, so a consumer could group `construct`
-            // by api and then get `api: undefined` for every request, error
-            // and hoist from the same client — the grouping working exactly
-            // until it was used.
             t: Date.now(), kind: 'error', plugin: name, api: (0, profile_1.refapi)(name),
             corr: fctx?.station$?.corr,
             err: {
@@ -602,13 +410,10 @@ class Station {
             },
         });
     }
-    // Op events from the hook bridge (design §3 item 3).
     _opEvent(name, ctx, outcome) {
         const st = ctx.station$ || {};
         this.emit({
             t: Date.now(), kind: 'op', plugin: name, api: (0, profile_1.refapi)(name), corr: st.corr,
-            // ctx.op is the SDK's resolved Operation: name + entity, in the
-            // descriptor's lowercase spelling.
             op: {
                 entity: String(ctx.op?.entity ?? ctx.entity?.name ?? ''),
                 op: String(ctx.op?.name ?? ''),
@@ -617,7 +422,6 @@ class Station {
             },
         });
     }
-    // --- the query/observe surface (design §3.2, §6) ---
     // One entry per LIVE INSTANCE (§6.1), and exhaustive: auto-tagged
     // entries are not collapsed here, because inspection, health
     // reporting and cleanup all need to enumerate the clients `create()`
@@ -637,14 +441,6 @@ class Station {
             warnings: e.warnings.slice(),
         }));
     }
-    // --- the declarative front door (design §6) ---
-    /** The instance, constructed on first call and CACHED: same name ->
-     * same object. That caching is what makes "get it where you need it"
-     * a real instruction - call it in a request handler, in a worker, in
-     * a test, and the first call pays construction while the rest are a
-     * map lookup.
-     *
-     * SYNCHRONOUS (§6.3), which is what bounds the loader to CommonJS. */
     sdk(name) {
         const cached = this.clients.get(name);
         if (null != cached) {
@@ -654,38 +450,9 @@ class Station {
         this.clients.set(name, client);
         return client;
     }
-    /** An UNCACHED client from the same resolved config plus overrides,
-     * for the case that genuinely wants a distinct one - a per-request
-     * credential scope, a test double. Deliberately the longer name.
-     *
-     * It registers under an AUTO-ASSIGNED TAG, because §7.5 registers
-     * every constructed adapter under its instance name and
-     * `station_bound_twice` fires on a second binding of one name: a
-     * second `create('stripe')` would otherwise throw, which is exactly
-     * the per-request case this exists for. The tag is the lowest unused
-     * positive integer, so an auto-tagged instance is an ORDINARY
-     * instance rather than a parallel identity scheme - `plugins()`, the
-     * placeholder, the event stream and `station_bound_twice` all keep
-     * working on one identity model.
-     *
-     * The SECRET NAME does not follow the assigned tag: it resolves from
-     * the DECLARED instance the tag was assigned under, so every client
-     * of one instance shares one broker cache entry rather than
-     * re-resolving per request (§5.3). */
     create(name, overrides) {
         return this.build(name, this.autotag(name), overrides);
     }
-    /** The lowest positive integer tag not already taken, by a LIVE
-     * instance or a DECLARED one.
-     *
-     * The registry alone was not enough: a profile may declare
-     * `stripe$1`, and until something constructs it `registry.has` says
-     * false — so `create('stripe$prod')` took that identity for a client
-     * built from the `stripe$prod` block. `instances()` then reported the
-     * declared `stripe$1` as live with the wrong client, and a later
-     * `sdk('stripe$1')` failed `station_bound_twice` against a binding
-     * that was never its own. Declaration reserves the name whether or
-     * not it has been built. */
     autotag(name) {
         const api = (0, profile_1.refapi)(name);
         for (let n = 1;; n++) {
@@ -710,36 +477,10 @@ class Station {
         }
         const api = (0, profile_1.refapi)(name);
         const entry = this.resolveFactory(api, block);
-        // §8.5 VALIDATES HERE, not only in `check()`. The schema arrives
-        // with the factory, so the moment a factory is resolved is the
-        // first moment validation is possible — and it was running in
-        // `check()` alone. Two gaps followed: production `sdk()` silently
-        // ignored an unknown option like `retry.retires`, and `check()`
-        // itself missed the case where the factory is discovered by the
-        // LOADER (its pre-check sees no registered factory, then `sdk()`
-        // loads and constructs unvalidated). One call here closes both,
-        // because every path to a constructor comes through this line.
         const faults = (0, feature_1.checkfeatures)(this.featuresOf(name).merged, entry.descriptor);
         if (0 < faults.length) {
-            // `Fault.code` is a plain string in `feature.ts`; the two codes it
-            // actually produces are both in the union, and `check()` passes
-            // the same value through untyped. Narrowed here rather than
-            // widening the union, so a new fault code is a compile error at
-            // the place that has to decide what it means.
             throw new error_1.StationError(faults[0].code, faults.map((f) => f.message).join('; '));
         }
-        // §8.4: compose the merged feature map into the ORDERED form and
-        // hand it to the constructor. No new seam - it is the same
-        // `options.feature` map `connect()` already uses for station's own
-        // placement, with more in it, and a JS object preserves the
-        // insertion order of string keys so the order rides the map.
-        //
-        // Station's own entry is composed AFTER the user merge and always
-        // wins (§8.4), which is why `station` is dropped here and added by
-        // `options()`: a config file that can switch off the component
-        // reading it is not a surface, it is a trap. `feature.station` is
-        // already `station_feature_reserved` at validation, so this is the
-        // second half of one rule rather than a second rule.
         const resolved = this.featuresOf(name);
         const fmap = {};
         for (const f of (0, feature_1.composefeatures)((0, feature_1.resolveorder)(resolved.merged).filter((o) => 'station' !== o.name))) {
@@ -752,38 +493,9 @@ class Station {
             ...(overrides || {}),
             feature: { ...fmap, ...((overrides || {}).feature || {}) },
         };
-        // §5.3, and `create`'s own doc comment: "the SECRET NAME does not
-        // follow the assigned tag: it resolves from the DECLARED instance
-        // the tag was assigned under."
-        //
-        // THE ALIAS IS RECORDED, NOT THE FIELDS. The first fix for this
-        // carried the declared `secret` through the feature options and
-        // stopped there — which left `policy`, `base` and everything else
-        // behind, so an auto-tagged client silently lost its declared
-        // instance's HOSTS ALLOWLIST and fell back to the wider api-level
-        // one. Carrying configuration a field at a time is how that
-        // happens; recording what the tag STANDS FOR is one rule that every
-        // lookup already goes through.
-        //
-        // Only when the tag was ASSIGNED — a caller naming its own is
-        // naming an instance, not aliasing one.
         if (null != as && as !== name) {
             this.aliasOf.set(as, name);
         }
-        // ...AND THE CARRIED ADAPTER RIDES EXTEND, exactly as it does on
-        // `connect`. §3.1's retrofit case — an SDK generated before the
-        // station feature, which `factoryFromModule` explicitly supports —
-        // has no generated feature to consume the `feature.station`
-        // activation this path sets, so declarative `sdk()` either failed
-        // on an unknown feature or returned an unregistered, unwrapped
-        // client with no credential injection and no events. The imperative
-        // path carried it and the declarative one did not, which is the
-        // whole defect.
-        //
-        // Safe on a REGENERATED SDK too: the constructor uses its own
-        // station feature and skips the extend copy by name, and both
-        // delegate to `featureBinding`, whose `_boundEntry` check no-ops a
-        // second arrival for the same client.
         const withAdapter = {
             ...opts,
             extend: [...(opts.extend || []), (0, adapter_1.adapterFeature)(this, opts)],
@@ -792,8 +504,6 @@ class Station {
         // imperative path, so registration has one spelling (§7.5).
         return entry.construct(this.options(as ?? name, withAdapter));
     }
-    /** §6.2's three paths, in order of preference: self-registration,
-     * `Station.provide`, then the loader. */
     resolveFactory(api, block) {
         const direct = (0, factory_1.factoryFor)(api);
         if (null != direct) {
@@ -811,9 +521,6 @@ class Station {
             'that self-registers, call Station.provide("' + api + '", ...), or ' +
             'set `api.' + api + '.package` so the loader can import it');
     }
-    /** `package` is honoured only from repo-scoped config (§6.3), and a
-     * user-level one is IGNORED WITH A WARNING rather than imported - it
-     * names code to load and sits outside the repo's review boundary. */
     loaderPackage(api, block) {
         const pkg = block.package;
         if (null == pkg || '' === pkg) {
@@ -858,12 +565,6 @@ class Station {
             await (0, loader_1.loadAsync)(api, pkg, block.export);
         }
     }
-    /** The merged, ordered feature set for one instance, WITH
-     * PROVENANCE (§8.7): which config level set each value.
-     *
-     * Provenance is the half that makes a fleet view usable rather than
-     * merely correct - at 26 instances "why is retry off here" is the
-     * question, and a merged map alone cannot answer it. */
     featuresOf(name) {
         const api = (0, profile_1.refapi)(name);
         const profiles = (this.raw?.profiles || {});
@@ -877,8 +578,6 @@ class Station {
             this.profile.name + '.sdk',
         ];
         const sources = (0, feature_1.featuresources)(base, overlay, api, name);
-        // Last writer per (feature, key) wins, and the level that wrote it
-        // is what `from` records.
         const from = {};
         sources.forEach((src, i) => {
             if (null == src || 'object' !== typeof src) {
@@ -896,23 +595,6 @@ class Station {
             }
         });
         let merged = (0, feature_1.mergefeatures)(sources);
-        // Policy budget (design §16): rps/concurrency ceilings ride "the
-        // SDK `ratelimit` feature, configured by station". Composed HERE,
-        // into the merged map every consumer reads, rather than patched in
-        // at construction alone - so `build()` orders it with the ordinary
-        // constraint-and-band rules (ordering and the station pin hold),
-        // `check()`'s §8.5 pass validates it against the SDK's own
-        // declaration (a budget on an SDK with no ratelimit feature is
-        // `station_feature_unknown`, not a setting that quietly did
-        // nothing), and the §8.7 fleet view answers "is ratelimit on?"
-        // truthfully, with `policy.budget` as the provenance level.
-        //
-        // `rps` maps to the token bucket's refill `rate` (per second -
-        // the same unit); `concurrency` to its capacity `burst`, the
-        // number of requests that can be in flight from a full bucket.
-        // POLICY WINS over a `feature.ratelimit` config entry on the keys
-        // it sets - it is enforcement, not a default - and other tuning
-        // keys survive beside it.
         const budget = this.blockFor(name)?.policy?.budget;
         if (null != budget && 'object' === typeof budget && !Array.isArray(budget)) {
             const prior = merged.ratelimit;
@@ -932,18 +614,6 @@ class Station {
             }
             merged = { ...merged, ratelimit: entry };
         }
-        // THE IMPLICIT STATION ENTRY, added for ORDERING ONLY. `station` is
-        // never in `merged` — `feature.station` is reserved and rejected at
-        // validation (§8.4) — so `checkpin` found no station row and
-        // returned immediately, every time. It was a permanent no-op: a
-        // constraint like `retry.order.after: 'station'` was treated as
-        // vacuous rather than rejected, and the reported order omitted the
-        // one feature whose position is supposedly pinned.
-        //
-        // Added here rather than into `merged`, which stays the user's own
-        // merge result. `build` already filters `station` out of the map it
-        // hands the constructor, because §8.4 composes station's entry
-        // after the user merge and always wins.
         const ordered = (0, feature_1.resolveorder)({ ...merged, station: { active: true } });
         (0, feature_1.checkpin)(ordered);
         return { ordered: ordered.map((o) => o.name), merged, from };
@@ -951,16 +621,6 @@ class Station {
     /** The fleet feature view: instance x feature, effective options, and
      * which config level set each (§8.7). */
     features(filter) {
-        // §8.7's documented shape is an OBJECT, and only the object form
-        // can express the question the view exists for: `{feature: 'debug'}`
-        // — "is debug on anywhere?", the one that is twenty greps today.
-        // The implementation took a bare string and compared it against
-        // both `name` and `api`, so every documented call returned an empty
-        // list, an object never equalling either string.
-        //
-        // The string form is kept as shorthand for "this instance or this
-        // api", because it is what the tests and the imperative path
-        // already use and it costs one line.
         const f = 'string' === typeof filter
             ? { instance: filter, api: filter, loose: true }
             : { ...(filter || {}), loose: false };
@@ -994,10 +654,6 @@ class Station {
             from: { [want]: row.from[want] || {} },
         }));
     }
-    /** Eagerly resolve and construct every ACTIVE instance - for CI
-     * (§6.6). The point is to turn availability errors, which are
-     * deliberately deferred to first use, into one failure at a moment
-     * somebody is watching. */
     check() {
         const ok = [];
         const failed = [];
@@ -1006,10 +662,6 @@ class Station {
                 continue;
             }
             try {
-                // §8.5 runs FIRST and needs no construction: the schema arrives
-                // with the factory, not with a live client, so a feature typo
-                // is a CI failure rather than a setting that quietly did
-                // nothing in production.
                 const entry = (0, factory_1.factoryFor)(row.api);
                 if (null != entry) {
                     const faults = (0, feature_1.checkfeatures)(this.featuresOf(row.name).merged, entry.descriptor);
@@ -1032,42 +684,14 @@ class Station {
         }
         return { ok, failed };
     }
-    /** Batch-resolve secrets for ACTIVE instances (§5.5).
-     *
-     * With no argument it warms the active ones only, because reaching
-     * for a credential belonging to a disabled integration is the wrong
-     * default. `warm(names)` warms exactly what it is given, inactive
-     * included, because an explicit name is an explicit request. */
     async warm(names) {
         const wanted = null != names
             ? names
             : this.instances().filter((r) => r.active).map((r) => r.name);
-        // CONCURRENT, not serial. Awaiting inside the loop made `warm`
-        // cost the SUM of every provider round-trip, which defeats the one
-        // thing the method exists for: resolving the fleet in a batch at
-        // startup rather than paying per first-request. sekreto exposes no
-        // batch `get`, so concurrency is the available shape.
-        //
-        // Names are deduped first: the broker's resolution cache is keyed
-        // by SECRET NAME (§5.3), so several instances sharing one api-level
-        // `secret` should cost one round-trip — and firing them together
-        // would race past the cache and make several.
         const plan = [];
         const warmed = [];
         const missed = [];
         for (const name of wanted) {
-            // THE REGISTRY IS THE AUTHORITY, and asking the profile instead
-            // was wrong twice: an IMPERATIVE instance has no `profile.sdk`
-            // block, so it was pushed to `missed` and never warmed at all —
-            // and the re-derivation dropped the in-code `secret` feature
-            // option, which beats the profile (§9). A registered instance
-            // already carries the resolved name.
-            // A NAME NOBODY DECLARED OR REGISTERED IS A MISS, not a lookup.
-            // Widening the fallback to cover imperative instances also let a
-            // typo — `stripe$prodd` — derive a secret name and call the
-            // provider, so a nonexistent instance could be reported `warmed`
-            // off a shared api-level credential. Registered OR declared, and
-            // nothing else.
             const entry = this.registry.get(name);
             if (null == entry && null == this.profile.sdk[name]) {
                 missed.push(name);
@@ -1151,12 +775,6 @@ class Station {
         return {
             mode: 'solo',
             profile: this.profile.name,
-            // §7.1: the registry is keyed by INSTANCE, so a status page that
-            // projects only `slug` shows two indistinguishable rows for
-            // `stripe$test` and `stripe$live` and omits the names it is keyed
-            // by — an operator cannot tell which one is unhealthy. `slug`
-            // stays for compatibility; `name` and `api` are what answer the
-            // question.
             plugins: this.plugins().map((p) => ({
                 name: p.name, api: p.api, slug: p.slug, rung: p.rung,
             })),
@@ -1169,10 +787,6 @@ class Station {
     refreshSecrets() {
         this.broker.refresh();
     }
-    // close(): flush (solo: nothing in flight), then warn on profile
-    // plugin keys that matched no registered plugin - a typo'd key
-    // silently configuring nothing is the worst outcome for a
-    // secrets-and-policy file (design §11).
     close() {
         if (this.closed) {
             return;