@voxgig/station 0.0.2 → 0.2.0

package/README.md

@@ -16,42 +16,37 @@ validates through [voxgig/struct](https://github.com/voxgig/struct).
 Those are the only two runtime dependencies a station library takes
 (design §10).
 
-## Two entries, one surface
-
-`package.json` `exports` selects between them by condition:
-
-| condition | entry | |
-|---|---|---|
-| default | `dist/src/index.js` | the node entry — the whole surface |
-| `browser` | `dist/src/index.browser.js` | the same surface **minus** the file-loading half |
-
-`loadConfig`, `findConfigFile` and `configScope` are node-only: they live
-in `profile.ts`, the one module here with top-level `node:` imports, and
-the browser entry simply does not carry them. So the browser graph pulls
-no `node:` builtin at all — `test/browser.test.ts` asserts it by walking
-the *compiled* `dist` files, the same requires a bundler follows, rather
-than trusting the source. The boundary, as that test states it: the walk
-covers this package's own modules; `@voxgig/sekreto` and
-`@voxgig/struct` are recorded but not entered, since their browser
-posture is their own.
-
-That is why `profilecore.ts` exists: the pure half of profile handling
-(selection, the ref grammar, the §3.3 merge) is data-in/data-out and the
-browser entry can reach it. `profile.ts` re-exports it, so no import path
-in the node half changes.
-
-On the browser entry `Station.open()` takes `config` as an object — the
-explicit-config path, which skips file loading entirely. With no `config`
-it behaves as node does when no `station.json` exists: null config,
-repo-scoped.
+## One entry
+
+`package.json` `exports` names a single entry, `dist/src/index.js`.
+
+There used to be two. A `browser` condition selected
+`dist/src/index.browser.js` — the same surface **minus** the file-loading
+half, so that no `node:` builtin was reachable from it — and three pieces
+of machinery existed to keep that true: `profilecore.ts` held the pure
+half of profile handling so the browser entry could reach it without
+`node:fs`; `Station.ts` took `loadConfig`/`configScope` through a
+`ConfigFileIO` seam that only the node entry registered; and
+`test/browser.test.ts` walked the compiled `dist` graph asserting no
+`node:` builtin appeared.
+
+**Station is server-side only**, so all of it is gone: the second entry,
+the condition, the seam, the split and the graph-walk test.
+`profilecore.ts` is merged back into `profile.ts`, and `Station.ts`
+imports `loadConfig` and `configScope` directly. Every import of
+`./profile` is unchanged — that path always re-exported the pure half.
+
+`setConfigFileIO` and its `ConfigFileIO` type were exported from this
+package and are removed with the seam. Nothing in this repository or any
+other voxgig port used them; the seam existed for the browser entry and
+for nothing else.
 
 ## Layout
 
 | | |
 |---|---|
 | `src/Station.ts` | the core: open/connect/adopt/options, sdk/create/check/warm, registry, transport middleware, the ref grammar |
-| `src/index.ts` | the node entry, and the registration that hands Station the file half |
-| `src/index.browser.ts` | the browser entry (above) |
+| `src/index.ts` | the entry: the public surface |
 | `src/adapter.ts` | `featureBinding` (the one binding entry) + the carried adapter |
 | `src/shape.ts` | `normalizeConfig`/`validateConfig`: the §4 grammar, the §4.4 workarounds, the §5.2 credential scans |
 | `src/config-shape.ts` | a verbatim mirror of [`spec/config-shape.json`](../spec/config-shape.json) — generated by `make sync-shape`, never edited by hand |
@@ -60,8 +55,7 @@ repo-scoped.
 | `src/loader.ts` | `loadSync`/`loadAsync`: CommonJS require + guarded dynamic import (§6.3) |
 | `src/descriptor.ts` | descriptor v1 normalizer + canonical serializer |
 | `src/secrets.ts` | the sekreto-backed broker + the placeholder |
-| `src/profile.ts` | the node-only file half: `station.json` lookup, config scope |
-| `src/profilecore.ts` | the pure half: profile selection, ref grammar, the §3.3 merge |
+| `src/profile.ts` | profile selection, the ref grammar, the §3.3 merge, `station.json` lookup and config scope |
 | `src/events.ts` | the bounded event ring + tap |
 | `src/error.ts` | the error-code catalog |
 | `src/types.ts` | shared types; the descriptor and event shapes are pinned by the corpus, so evolve them additively |

package/dist/src/Station.d.ts

@@ -1,51 +1,10 @@
 import { Binding, PluginEntry, ResolvedInstance, SdkBlock, StationEvent, StationOptions } from './types';
-/** The FILE half of config loading, behind a seam so this module never
- * imports it (§2.2, §17 Phase 1: no top-level `node:` imports reachable
- * from the browser entry). The NODE entry (`index.ts`) registers
- * `profile.ts`'s loadConfig/configScope at module load; the browser
- * entry registers nothing, so a browser `open()` with no explicit
- * `config` behaves exactly as node does when no station.json exists -
- * null config, repo-scoped - rather than inventing a third state.
- * Passing `config` (the documented browser spelling, §2.2) skips the
- * seam entirely on both entries, which is the pre-existing
- * explicit-config path unchanged. */
-export type ConfigFileIO = {
-    loadConfig: (from?: string) => any;
-    configScope: (from?: string) => 'repo' | 'user' | 'none';
-};
-export declare function setConfigFileIO(io: ConfigFileIO): void;
-/** §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;
@@ -71,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;
@@ -128,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: {
@@ -203,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: {
@@ -215,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[];