@voxgig/station 0.0.1

package/src/error.ts

@@ -0,0 +1,64 @@
+// Error codes follow the SDKs' house grammar (design §14):
+// <subject>_<condition>, absence as no_<thing>, gates as _allow.
+// The `errors` corpus section pins the exact strings.
+
+const CODES = [
+  'station_no_proxy',
+  'station_secret_no_value',
+  'station_secret_error',
+  'station_secret_name',
+  'station_host_allow',
+  'station_grant_expired',
+  'station_wrap_order',
+  'station_protocol',
+  'station_no_plugin',
+  'station_no_entity',
+  'station_no_op',
+  'station_agent_allow',
+  'station_body_limit',
+  'station_replay_lossy',
+  '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',
+  'station_feature_reserved',
+
+  // Instances (design §6.4). `as` is a tag, not a free name: a full ref
+  // whose name is not the SDK's api slug is this.
+  'station_instance_api',
+  'station_no_instance',
+  'station_instance_inactive',
+  'station_sdk_load',
+  'station_no_factory',
+  'station_factory_conflict',
+
+  // Features (design §8.4, §8.5). The checker is derived from the SDK's
+  // own declaration, so a feature typo is a CI failure rather than a
+  // setting that quietly did nothing in production.
+  'station_feature_unknown',
+  'station_feature_option',
+  'station_feature_order',
+] as const
+
+export type StationErrorCode = typeof CODES[number]
+
+export class StationError extends Error {
+  code: StationErrorCode
+
+  constructor(code: StationErrorCode, message: string) {
+    super(code + ': ' + message)
+    this.name = 'StationError'
+    this.code = code
+  }
+}
+
+export function isKnownCode(code: string): boolean {
+  return (CODES as readonly string[]).includes(code)
+}

package/src/events.ts

@@ -0,0 +1,45 @@
+import { StationEvent } from './types'
+
+// The solo event surface (design §6): a bounded ring buffer plus a live
+// tap with serialized callbacks. Events never fail an operation; overflow
+// drops oldest and the drop count is visible in status().
+
+export class EventBuffer {
+  private ring: StationEvent[] = []
+  private max: number
+  private drops = 0
+  private taps: ((ev: StationEvent) => void)[] = []
+
+  constructor(max?: number) {
+    this.max = null == max ? 1000 : max
+  }
+
+  emit(ev: StationEvent): void {
+    this.ring.push(ev)
+    if (this.ring.length > this.max) {
+      this.ring.shift()
+      this.drops++
+    }
+    // Serialized, and a throwing tap must not fail the operation that
+    // emitted the event.
+    for (const fn of this.taps) {
+      try { fn(ev) } catch (_e) { }
+    }
+  }
+
+  events(): StationEvent[] {
+    return this.ring.slice()
+  }
+
+  tap(fn: (ev: StationEvent) => void): () => void {
+    this.taps.push(fn)
+    return () => {
+      const i = this.taps.indexOf(fn)
+      if (-1 !== i) { this.taps.splice(i, 1) }
+    }
+  }
+
+  status(): { buffered: number, dropped: number } {
+    return { buffered: this.ring.length, dropped: this.drops }
+  }
+}

package/src/factory.ts

@@ -0,0 +1,93 @@
+/* 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'
+
+export type Factory = {
+  construct: (options: any) => any
+  config: any
+}
+
+export type FactoryEntry = {
+  api: string
+  construct: (options: any) => any
+  config: any
+  descriptor: any
+  warnings: string[]
+}
+
+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)
+  if (null != prior) {
+    if (prior.construct === factory.construct && prior.config === factory.config) {
+      return prior
+    }
+    throw new StationError('station_factory_conflict',
+      'two different factories registered for api "' + slug + '"; a ' +
+      'process has one build of an SDK, and picking between two ' +
+      'silently is not a thing to do quietly')
+  }
+
+  // AT PROVIDE TIME, which is the whole point of carrying `config`.
+  const { descriptor, warnings } = normalizeDescriptor(factory.config, undefined)
+  const entry: FactoryEntry = {
+    api: slug,
+    construct: factory.construct,
+    config: factory.config,
+    descriptor,
+    warnings,
+  }
+  TABLE.set(slug, entry)
+  return entry
+}
+
+export function factoryFor(api: string): FactoryEntry | undefined {
+  return TABLE.get(String(api))
+}
+
+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

@@ -0,0 +1,321 @@
+/* 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'
+
+// ---------------------------------------------------------------------
+// §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) {
+    if (!ismap(src)) { continue }
+    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[] {
+  return [
+    base?.feature,
+    base?.api?.[api]?.feature,
+    base?.sdk?.[ref]?.feature,
+    overlay?.feature,
+    overlay?.api?.[api]?.feature,
+    overlay?.sdk?.[ref]?.feature,
+  ]
+}
+
+// ---------------------------------------------------------------------
+// §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 }
+  return BAND_DEFAULT
+}
+
+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>()
+  names.forEach((n, i) => pos.set(n, i))
+
+  const band = new Map<string, number>()
+  for (const n of names) {
+    const o = ismap(merged[n]) ? merged[n].order : undefined
+    const b = ismap(o) && 'number' === typeof o.band ? o.band : defaultband(n)
+    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()) }
+
+  const listof = (v: any): string[] =>
+    null == v ? [] : (Array.isArray(v) ? v : [v]).map(String)
+
+  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) }
+    }
+    for (const other of listof(o.before)) {
+      if (inner.has(other)) { inner.get(n)!.add(other) }
+    }
+  }
+
+  const indeg = new Map<string, number>()
+  for (const n of names) { indeg.set(n, 0) }
+  for (const n of names) {
+    for (const m of inner.get(n)!) { indeg.set(m, (indeg.get(m) || 0) + 1) }
+  }
+
+  // Kahn, picking the lowest band first (outermost), then declaration
+  // position — so ties break the same way in every port.
+  const ready: string[] = names.filter((n) => 0 === indeg.get(n))
+  const out: Ordered[] = []
+  const pick = (): string => {
+    ready.sort((a, b) => {
+      const d = band.get(a)! - band.get(b)!
+      return 0 !== d ? d : pos.get(a)! - pos.get(b)!
+    })
+    return ready.shift()!
+  }
+
+  while (0 < ready.length) {
+    const n = pick()
+    out.push({ name: n, band: band.get(n)!, entry: merged[n] })
+    for (const m of inner.get(n)!) {
+      indeg.set(m, indeg.get(m)! - 1)
+      if (0 === indeg.get(m)) { ready.push(m) }
+    }
+  }
+
+  if (out.length !== names.length) {
+    const stuck = names.filter((n) => !out.some((o) => o.name === n)).sort()
+    throw new StationError('station_feature_order',
+      'feature ordering constraints form a cycle among [' +
+      stuck.join(', ') + ']')
+  }
+
+  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 }
+
+  const base = ordered.findIndex((o) => 'test' === o.name)
+  // station must be the innermost wrapper: last, or immediately
+  // outside the base-transport feature when one is active.
+  const want = -1 === base ? ordered.length - 1 : base - 1
+  if (i !== want) {
+    throw new StationError('station_feature_order',
+      'an ordering would move `station` away from immediately outside ' +
+      'the base transport; its position is pinned innermost and is not ' +
+      'orderable (§8.4)')
+  }
+}
+
+// ---------------------------------------------------------------------
+// §8.5 — the checker, derived from the descriptor
+// ---------------------------------------------------------------------
+
+export type FeatureFault = {
+  code: string
+  feature: string
+  key?: string
+  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[] {
+  const faults: FeatureFault[] = []
+  const declared: any[] = descriptor?.features || []
+  const byname = new Map<string, any>()
+  for (const f of declared) { byname.set(String(f.name), f) }
+
+  for (const name of Object.keys(merged).sort()) {
+    const spec = byname.get(name)
+    if (null == spec) {
+      faults.push({
+        code: 'station_feature_unknown',
+        feature: name,
+        message: 'the SDK has no feature "' + name + '"; it declares [' +
+          Array.from(byname.keys()).sort().join(', ') + ']',
+      })
+      continue
+    }
+
+    const entry = merged[name]
+    if (!ismap(entry)) { continue }
+    const defaults = ismap(spec.options) ? spec.options : {}
+
+    for (const key of Object.keys(entry).sort()) {
+      if (-1 !== RESERVED_KEYS.indexOf(key)) { continue }
+
+      if (!(key in defaults)) {
+        // THE CASE THAT ACTUALLY BITES: `retry.retires: 5` is accepted
+        // and silently ignored today, because makeOptions' feature spec
+        // is `$OPEN` per feature so the SDK cannot catch it and nothing
+        // else looks.
+        faults.push({
+          code: 'station_feature_option',
+          feature: name,
+          key,
+          message: 'feature "' + name + '" declares no option "' + key +
+            '"; it declares [' + Object.keys(defaults).sort().join(', ') + ']',
+        })
+        continue
+      }
+
+      const want = kindof(defaults[key])
+      const got = kindof(entry[key])
+      if (want !== got) {
+        faults.push({
+          code: 'station_feature_option',
+          feature: name,
+          key,
+          message: 'feature "' + name + '" option "' + key + '" expects ' +
+            want + ', but found ' + got + ': ' + JSON.stringify(entry[key]),
+        })
+      }
+    }
+  }
+
+  return faults
+}
+
+/** Compose the merged map into the ORDERED ARRAY FORM the constructor
+ * takes. No new seam: it is what `connect()` already does for station's
+ * own placement, with more in it. */
+export function composefeatures(ordered: Ordered[]): any[] {
+  return ordered.map((o) => {
+    const entry = ismap(o.entry) ? o.entry : {}
+    const out: any = { name: o.name, active: true }
+    for (const k of Object.keys(entry)) {
+      if (-1 !== RESERVED_KEYS.indexOf(k)) { continue }
+      out[k] = entry[k]
+    }
+    return out
+  })
+}
+
+function kindof(v: any): string {
+  if (null === v || undefined === v) { return 'null' }
+  if (Array.isArray(v)) { return 'list' }
+  if ('number' === typeof v) { return 'number' }
+  if ('object' === typeof v) { return 'map' }
+  return typeof v
+}
+
+function ismap(v: any): boolean {
+  return null != v && 'object' === typeof v && !Array.isArray(v)
+}

package/src/index.browser.ts

@@ -0,0 +1,56 @@
+// @voxgig/station - one control surface for outbound integrations.
+//
+// THE BROWSER ENTRY (§2.2, §17 Phase 1), selected by the `browser`
+// condition in package.json `exports`. The same surface as `index.ts`
+// MINUS the file-loading half - `loadConfig`, `findConfigFile` and
+// `configScope` are node-only (`profile.ts`, the one module in this
+// package with top-level `node:` imports) and are simply not here, so
+// this entry's module graph pulls no `node:` builtin
+// (`test/browser.test.ts` walks the compiled graph and asserts it).
+//
+// `Station.open()` on this entry takes `config` as an OBJECT - the
+// pre-existing explicit-config path, which skips file loading entirely.
+// With no `config` at all it behaves exactly as node does when no
+// station.json exists: null config, repo-scoped. The ConfigFileIO seam
+// stays unregistered here; a host that genuinely has a config store can
+// register its own through `setConfigFileIO`.
+//
+// §2.2's honesty note stands: in the browser R1/R2 isolation does not
+// exist - an injected credential is readable by page code and DevTools
+// - so browser station is observability-only with app-held credentials
+// until a same-origin proxy endpoint exists.
+
+export { Station, instanceRef, setConfigFileIO } from './Station'
+export type { ConfigFileIO } from './Station'
+export { provide, factoryFor, provided, resetFactories } from './factory'
+export type { Factory, FactoryEntry } from './factory'
+export {
+  DEFAULT_EXPORT, camelify, checkPackage, factoryFromModule, loadAsync, loadSync,
+} from './loader'
+export { adapterFeature, featureBinding } from './adapter'
+export type { FeatureBinding } from './adapter'
+export { StationError } from './error'
+export {
+  canonicalSerialize,
+  envtoken,
+  normalizeDescriptor,
+  secretnameDefault,
+} from './descriptor'
+export { placeholderFor } from './secrets'
+export { refapi, resolveProfile, selectProfile } from './profilecore'
+export type { ResolvedProfile } from './profilecore'
+export {
+  BLOCK_DEFAULTS, MERGE_SENSITIVE, PROFILE_DEFAULTS,
+  configShape, normalizeConfig, validateConfig,
+} from './shape'
+export type {
+  Binding,
+  Descriptor,
+  PolicyBlock,
+  Profile,
+  ResolvedInstance,
+  SdkBlock,
+  StationConfig,
+  StationEvent,
+  StationOptions,
+} from './types'

package/src/index.ts

@@ -0,0 +1,50 @@
+// @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 { provide, factoryFor, provided, resetFactories } from './factory'
+export type { Factory, FactoryEntry } from './factory'
+export {
+  DEFAULT_EXPORT, camelify, checkPackage, factoryFromModule, loadAsync, loadSync,
+} from './loader'
+export { adapterFeature, featureBinding } from './adapter'
+export type { FeatureBinding } from './adapter'
+export { StationError } from './error'
+export {
+  canonicalSerialize,
+  envtoken,
+  normalizeDescriptor,
+  secretnameDefault,
+} from './descriptor'
+export { placeholderFor } from './secrets'
+export {
+  configScope, findConfigFile, loadConfig, refapi, resolveProfile,
+  selectProfile,
+} from './profile'
+export type { ResolvedProfile } from './profile'
+export {
+  BLOCK_DEFAULTS, MERGE_SENSITIVE, PROFILE_DEFAULTS,
+  configShape, normalizeConfig, validateConfig,
+} from './shape'
+export type {
+  Binding,
+  Descriptor,
+  PolicyBlock,
+  Profile,
+  ResolvedInstance,
+  SdkBlock,
+  StationConfig,
+  StationEvent,
+  StationOptions,
+} from './types'