@voxgig/station 0.1.0 → 0.2.0

package/dist/src/Station.d.ts

@@ -1,36 +1,10 @@
 import { Binding, PluginEntry, ResolvedInstance, SdkBlock, StationEvent, StationOptions } from './types';
-/** §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. */
 export declare function instanceRef(api: string, fopts?: any): string;
 export declare function checkInstanceName(name: string): boolean;
 export declare function checkInstanceTag(tag: string): boolean;
 export declare class Station {
     private static ambient;
     private static ambientOpts;
-    /** §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: string, factory: any): void;
     private opts;
     private profile;
@@ -56,51 +30,17 @@ export declare class Station {
     private construct;
     options(a?: any, b?: any): any;
     _boundEntry(client: any): PluginEntry | 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. */
     private blockFor;
-    /** 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`. */
     private declaredRef;
     _register(client: any, config: any, options: any, _calleropts: any, fopts?: any): {
         binding: Binding;
         profilePlugin?: SdkBlock;
     };
     private descriptorCache;
-    /** 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. */
     private describe;
     _hoist(name: string, value: string): void;
     _transport(name: string, inner: any, fctx: any, fullurl: string, fetchdef: any): Promise<any>;
+    private scrubbed;
     private emitHttp;
     private emitErr;
     _opEvent(name: string, ctx: any, outcome: string): void;
@@ -113,63 +53,16 @@ export declare class Station {
         secretname?: string;
         warnings: string[];
     }[];
-    /** 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: string): any;
-    /** 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: string, overrides?: any): any;
-    /** 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. */
     private autotag;
     private build;
-    /** §6.2's three paths, in order of preference: self-registration,
-     * `Station.provide`, then the loader. */
     private resolveFactory;
-    /** `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. */
     private loaderPackage;
     /** ts/js only: preload ESM packages into the factory table, after
      * which `sdk()` is synchronous again for everything (§6.3). One
      * `await` at startup rather than one per call site. */
     load(): Promise<void>;
-    /** 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: string): {
         ordered: string[];
         merged: {
@@ -188,10 +81,6 @@ export declare class Station {
         api?: string;
         feature?: string;
     }): any[];
-    /** 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(): {
         ok: string[];
         failed: {
@@ -200,12 +89,6 @@ export declare class Station {
             message: string;
         }[];
     };
-    /** 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. */
     warm(names?: string[]): Promise<{
         warmed: string[];
         missed: string[];