@voxgig/station 0.1.0 → 0.2.0

package/src/profile.ts

@@ -1,14 +1,3 @@
-/* Profile handling, whole: the pure half - selection, the ref grammar
- * and the §3.3 merge - and the file half that finds and reads
- * station.json plus the scope rule hanging off where it was found.
- *
- * These were two modules. `profilecore.ts` held the pure half so the
- * BROWSER ENTRY could reach it without pulling `node:fs`, and `Station`
- * reached the file half through a `ConfigFileIO` seam the node entry
- * registered. Station is server-side only, so the split, the seam and
- * the second entry are all gone and this is one module again. Every
- * import of `./profile` is unchanged - that path always re-exported the
- * pure half. */
 
 import Fs from 'node:fs'
 import Os from 'node:os'
@@ -21,14 +10,6 @@ import { StationError } from './error'
 import { BLOCK_DEFAULTS } from './shape'
 import { StationConfig, SdkBlock } from './types'
 
-// Profile selection: VOXGIG_STATION_PROFILE, else the open() option,
-// else 'default' (design §3.5 - env vars rank above station.json but
-// below open() opts; profile NAME selection follows the same order with
-// open() opts winning).
-//
-// `process` is read directly. It used to go through a `typeof` guard
-// because the browser entry reached this code and has no `process`;
-// station is server-side only, so the guard guarded nothing.
 export function selectProfile(optProfile?: string): string {
   if (null != optProfile && '' !== optProfile) { return optProfile }
   const env = process.env.VOXGIG_STATION_PROFILE
@@ -36,14 +17,6 @@ export function selectProfile(optProfile?: string): string {
   return 'default'
 }
 
-// The api half of a ref is the substring before the first `$`, and an
-// untagged ref IS an api slug (design §3.4) - which is why the whole
-// `plugin` -> `sdk` migration is a key rename and nothing else.
-//
-// LEXICAL, and that is the point: under the old free-form identity
-// which api an instance used was itself a merged value, so the merge
-// could not be a flat pass over both maps and a port that got the
-// phasing wrong silently picked another api's defaults (§3.3).
 export function refapi(ref: string): string {
   const at = String(ref).indexOf('$')
   return -1 === at ? String(ref) : String(ref).slice(0, at)
@@ -52,23 +25,12 @@ export function refapi(ref: string): string {
 export type ResolvedProfile = {
   name: string
   providers: any[]
-  // The api-level defaults in effect for this profile, base ⊕ overlay
-  // per api slug. A REPORT, not an input to the instance merge below -
-  // collapsing each namespace first and composing at the end is the
-  // exact algorithm §3.3 forbids.
   api: Record<string, SdkBlock>
   // Instances, keyed by ref. An `api` block declares no instance of its
   // own (§3.1), so it never creates an entry here.
   sdk: Record<string, SdkBlock>
 }
 
-// Shallow merge, per key, left to right - each source over the one
-// before it. Declared rather than assumed: plugin's library default is
-// a deep map merge, and an allowlist that widens because two precedence
-// levels merged is the failure this rule exists to prevent
-// (station-and-plugin.md §2.5). The visible consequence: an overlay's
-// `policy` REPLACES the base's entirely rather than merging `hosts`
-// into it. That is also the safer reading for an allowlist.
 function shallow(...sources: any[]): any {
   const out: any = {}
   for (const src of sources) {
@@ -78,29 +40,6 @@ function shallow(...sources: any[]): any {
   return out
 }
 
-// Merge the base profile ('default') with the selected overlay.
-//
-// §3.3's total order, for the two block levels - lowest precedence
-// first:
-//
-//   base.api[<api>] ⊕ base.sdk[<ref>] ⊕ overlay.api[<api>] ⊕ overlay.sdk[<ref>]
-//
-// PROFILE SPECIFICITY OUTRANKS BLOCK SPECIFICITY. A `prod` api-level
-// `base` beats a `default` instance-level `base`, because that is what
-// an environment overlay is for; within one profile the instance beats
-// the api default, because that is what an instance is for.
-//
-// THIS IS ONE FLAT LEFT-TO-RIGHT MERGE AND MUST NOT BE REORGANIZED INTO
-// "collapse each namespace, then put instance over api". Collapsing
-// first computes (base.api ⊕ overlay.api) and (base.sdk ⊕ overlay.sdk)
-// and then lets EVERY instance value beat EVERY api value - the exact
-// opposite. A production `api.stripe.policy` would then fail to
-// override a default profile's `sdk.stripe$test.policy`, silently
-// keeping the wider allowlist in production.
-//
-// `secrets.providers` replaces wholesale, never merges (§3.5, §5.2):
-// chain order decides which store wins, so a positional merge would be
-// actively dangerous.
 export function resolveProfile(
   config: StationConfig | null, profileName: string
 ): ResolvedProfile {
@@ -129,13 +68,6 @@ export function resolveProfile(
       overlay.sdk?.[ref],
     )
 
-    // Defaults are applied ONCE, to the fully merged instance, and this
-    // is the rule §4.2's normalization must not be confused with. Had
-    // the overlay block carried a synthesized `active: true` into the
-    // merge, a one-key environment override would silently re-enable an
-    // integration the base declared `active: false` - live in
-    // production despite being declared inactive. The `instance` corpus
-    // section carries exactly this case.
     for (const k of Object.keys(BLOCK_DEFAULTS)) {
       if (undefined === merged[k]) { merged[k] = BLOCK_DEFAULTS[k]() }
     }
@@ -148,23 +80,6 @@ export function resolveProfile(
   return { name: profileName, providers, api, sdk }
 }
 
-// A configured secret name sekreto would reject is caught at profile
-// load, not first request (§14 station_secret_name) - and then the
-// derived names are checked for uniqueness, because envtoken is LOSSY.
-//
-// It collapses any run of non-alphanumerics to `_`, so `$` and `-` are
-// indistinguishable downstream: the ref `stripe$test` and an untagged
-// instance of an api slugged `stripe-test` both derive
-// `stripe_test.apikey`. That pairing is the realistic one rather than a
-// contrived one, because api slugs are hyphenated by construction - so
-// a fleet with both a `stripe-test` api and a `test` instance of
-// `stripe` collides by default. Since the resolution cache is keyed by
-// secret name (§5.3), the second instance would silently receive the
-// first's value.
-//
-// Two instances that EXPLICITLY name the same secret are not a
-// collision - that is the shared-key case the api-level `secret` exists
-// for, and saying so out loud is how you ask for it.
 function checksecrets(
   sdk: Record<string, SdkBlock>, profileName: string
 ): void {
@@ -206,9 +121,6 @@ function sortedkeys(...maps: any[]): string[] {
   return Array.from(keys).sort()
 }
 
-// station.json lookup: cwd upward to the repo root, then
-// ~/.voxgig/station.json (design §3.5). A repo root is where .git lives;
-// with no repo the walk stops at the filesystem root.
 export function findConfigFile(from?: string): string | null {
   let dir = Path.resolve(from || process.cwd())
   for (; ;) {
@@ -239,13 +151,6 @@ export function loadConfig(from?: string): StationConfig | null {
   }
 }
 
-// Which side of the review boundary the config came from (§6.3).
-//
-// `package` and `export` are honoured only from REPO-SCOPED config,
-// because a user-level file is outside the repo's review boundary and a
-// `package` key arriving from it names code to import. Everything else
-// in a user-level config still applies - this narrows one key rather
-// than distrusting the file.
 export function configScope(from?: string): 'repo' | 'user' | 'none' {
   const file = findConfigFile(from)
   if (null == file) { return 'none' }

package/src/secrets.ts

@@ -1,4 +1,5 @@
 import { Sekreto, SekretoError } from '@voxgig/sekreto'
+import { allplugins } from '@voxgig/sekreto/plugins'
 
 import { StationError } from './error'
 
@@ -6,14 +7,109 @@ import { StationError } from './error'
 // broker holds resolved values privately - they never enter options,
 // events, or captures; the SDK sees only the placeholder.
 
-// §7.2: keyed by INSTANCE. Two live instances of one api must have
-// distinct placeholders or the injection seam cannot tell which
-// credential a header wants. For an untagged instance this is the api
-// slug, so the single-instance case is unchanged.
 export function placeholderFor(slug: string): string {
   return '[station:' + slug + ']'
 }
 
+const UNRESERVED = /^[A-Za-z0-9\-._~]$/
+const HEXPAIR = /^[0-9A-Fa-f]{2}$/
+
+// Every UTF-8 byte outside RFC 3986's unreserved set becomes upper-case %XX.
+export function encodeQueryValue(value: string): string {
+  let out = ''
+  for (const byte of Buffer.from(value, 'utf8')) {
+    const ch = String.fromCharCode(byte)
+    out += byte < 0x80 && UNRESERVED.test(ch)
+      ? ch
+      : '%' + byte.toString(16).toUpperCase().padStart(2, '0')
+  }
+  return out
+}
+
+function matchAt(text: string, at: number, end: number, placeholder: string): number {
+  let i = at
+  for (const ch of placeholder) {
+    if (i < end && text[i] === ch) { i++; continue }
+    const hex = text.substring(i + 1, i + 3)
+    if (i + 3 <= end && '%' === text[i] && HEXPAIR.test(hex) &&
+      parseInt(hex, 16) === ch.charCodeAt(0)) {
+      i += 3
+      continue
+    }
+    return -1
+  }
+  return i - at
+}
+
+// The placeholder becomes the value in header values and in the URL query,
+// where an SDK percent-encodes it (any hex case) and the value is encoded in
+// turn. The path and fragment are never touched; the headers are a copy.
+export function substitute(url: string, headers: Record<string, any> | null | undefined,
+  placeholder: string, value: string): { url: string, headers: Record<string, any> } {
+  const out: Record<string, any> = { ...(headers || {}) }
+  if ('' === placeholder) { return { url, headers: out } }
+
+  for (const h of Object.keys(out)) {
+    const v = out[h]
+    if ('string' === typeof v && v.includes(placeholder)) {
+      out[h] = v.split(placeholder).join(value)
+    }
+  }
+
+  const q = url.indexOf('?')
+  const hash = url.indexOf('#')
+  if (-1 === q || (-1 !== hash && hash < q)) { return { url, headers: out } }
+  const end = -1 === hash ? url.length : hash
+  const encoded = encodeQueryValue(value)
+  let query = ''
+  for (let i = q + 1; i < end;) {
+    const n = matchAt(url, i, end, placeholder)
+    if (0 < n) {
+      query += encoded
+      i += n
+    }
+    else {
+      query += url[i]
+      i++
+    }
+  }
+  return { url: url.substring(0, q + 1) + query + url.substring(end), headers: out }
+}
+
+// Every form of every value is matched against the original text and the
+// union of the matches redacted, so no replacement can hide another form.
+function redactValues(text: string, values: string[]): string {
+  const forms = new Set<string>()
+  for (const value of values) {
+    if ('' !== value) {
+      forms.add(value)
+      forms.add(encodeQueryValue(value))
+    }
+  }
+  const reach = (at: number): number => {
+    let end = at
+    for (const form of forms) {
+      if (at + form.length > end && text.startsWith(form, at)) { end = at + form.length }
+    }
+    return end
+  }
+
+  let out = ''
+  for (let i = 0; i < text.length;) {
+    let stop = reach(i)
+    if (stop === i) {
+      out += text[i++]
+      continue
+    }
+    for (let j = i + 1; j < stop; j++) {
+      stop = Math.max(stop, reach(j))
+    }
+    out += '[redacted]'
+    i = stop
+  }
+  return out
+}
+
 export class SecretBroker {
   private sekreto: Sekreto
   // Values hoisted by adopt() from resident options.apikey (design §3.1).
@@ -23,7 +119,7 @@ export class SecretBroker {
   private held: string[] = []
 
   constructor(providers: any[]) {
-    this.sekreto = new Sekreto({ providers })
+    this.sekreto = new Sekreto({ plugins: allplugins, providers })
   }
 
   hoist(slug: string, value: string): void {
@@ -31,21 +127,6 @@ export class SecretBroker {
     this.held.push(value)
   }
 
-  // Resolve the value for a plugin's secret name. Misses and store
-  // errors keep sekreto's distinction (design §5.2): a miss is
-  // station_secret_no_value, a store that could not answer is
-  // station_secret_error with sekreto's message intact - and never a
-  // retry against a weaker store (sekreto owns the chain).
-  // OVERRIDES ARE KEYED BY INSTANCE; THE RESOLUTION CACHE IS KEYED BY
-  // SECRET NAME (§5.3). A hoisted credential belongs to the one instance
-  // it was resident in, but a resolved VALUE belongs to the name it was
-  // resolved for - so several instances sharing one api-level `secret`
-  // cost one lookup rather than one each, and every client an
-  // auto-tagged `create()` produces shares the declared instance's entry
-  // instead of re-resolving per request.
-  //
-  // Keying the cache by instance instead is the defect this replaces: at
-  // 26 instances over 20 apis it turns one store round-trip into 26.
   async value(slug: string, name: string): Promise<string> {
     const override = this.overrides.get(slug)
     if (null != override) { return override }
@@ -70,19 +151,10 @@ export class SecretBroker {
     return value
   }
 
-  // Exact-value scrub, deliberately WITHOUT sekreto's four-character
-  // readability floor (design §7 as revised): on boundaries where the
-  // promise is absolute, every held value is scrubbed whatever its
-  // length. sekreto's own redact() runs too, covering values resolved
-  // by the underlying instance that station never held.
+  // sekreto's redact runs second; run first, it could split an encoded form.
   scrub(text: string): string {
-    let out = this.sekreto.redact(text)
-    for (const value of this.held) {
-      if ('' !== value) {
-        out = out.split(value).join('[redacted]')
-      }
-    }
-    return out
+    const raw = 'string' === typeof text ? text : ''
+    return this.sekreto.redact(redactValues(raw, this.held))
   }
 
   // Drop caches so the next resolve asks the stores again (rotation

package/src/shape.ts

@@ -1,21 +1,3 @@
-/* The config grammar, as data (design §4).
- *
- * TWO STEPS, AND THE FIRST IS WHAT MAKES THE SECOND HONEST.
- *
- * struct drops the unexpected-key check for a map whose spec node ends
- * up empty - "an empty spec object means the object can be open". An
- * optional key is `['$ONE','$NIL', spec]`, and when the data does not
- * carry that key the validator REMOVES it from the spec node. So a
- * block whose keys are all optional degenerates into an open map
- * exactly when the data has none of them, and `{"solar": {"bass": 1}}`
- * validates clean - the one property the whole exercise is for,
- * silently absent in the one case that matters.
- *
- * So: normalizeConfig materializes every documented default, and
- * validateConfig then runs a shape WITH NO OPTIONAL CONTAINERS AT ALL.
- * After normalization every container is present, so the shape can
- * require them, so unexpected-key detection is live at every level and
- * every error names its path. */
 
 import { clone, validate } from '@voxgig/struct'
 import { validname } from '@voxgig/sekreto'
@@ -24,9 +6,6 @@ import { CONFIG_SHAPE } from './config-shape'
 import { StationError } from './error'
 import { envtoken } from './descriptor'
 
-// ---------------------------------------------------------------------
-// The defaults table - ONE table, two callers
-// ---------------------------------------------------------------------
 
 /** Profile-level containers. Safe to materialize early either way:
  * they are containers, and a missing one merges as empty regardless. */
@@ -37,15 +16,6 @@ export const PROFILE_DEFAULTS: { [k: string]: () => any } = {
   feature: () => ({}),
 }
 
-/** Block-level. `feature` is a container and safe early.
- *
- * `active` IS NOT, and that is the whole timing rule: a default
- * synthesized into an OVERLAY block overwrites the base's real value
- * and silently reactivates an integration the base deliberately barred
- * (§3.3). So the two consumers read this same table at different
- * moments - validateConfig before, to every block, because a block with
- * no present keys is an open map; the resolver AFTER, to the merged
- * instance, because an absent key must stay absent through the merge. */
 export const BLOCK_DEFAULTS: { [k: string]: () => any } = {
   active: () => true,
   feature: () => ({}),
@@ -60,12 +30,6 @@ export const MERGE_SENSITIVE = ['active']
 // normalizeConfig
 // ---------------------------------------------------------------------
 
-/** Materialize every documented default, DEFENSIVELY: a node that is
- * not the kind it expects is left alone for validate to reject with a
- * proper message. Pure data-in/data-out, which is what makes it
- * portable to 22 languages and expressible in the corpus.
- *
- * THE NORMALIZED FORM IS AN INPUT TO VALIDATION AND TO NOTHING ELSE. */
 export function normalizeConfig(raw: any): any {
   if (!ismap(raw)) { return raw }
   const out: any = { ...raw }
@@ -83,7 +47,6 @@ export function normalizeConfig(raw: any): any {
     for (const k of Object.keys(PROFILE_DEFAULTS)) {
       if (undefined === prof[k]) { prof[k] = PROFILE_DEFAULTS[k]() }
     }
-    // A `secrets` written without `providers` still gets the chain.
     if (ismap(prof.secrets) && undefined === prof.secrets.providers) {
       prof.secrets = { ...prof.secrets, providers: [{ kind: 'env' }] }
     }
@@ -111,16 +74,6 @@ export function normalizeConfig(raw: any): any {
   return out
 }
 
-/** Per feature entry, at every level: `active` -> true.
- *
- * A FEATURE NAMED IN THE CONFIG IS ONE YOU ARE ASKING FOR. The SDK's
- * own default is `active: false` for all but `log`, and
- * `{"retry": {"retries": 3}}` plainly means "retry, with three
- * attempts". It also keeps the feature map closed, for the same reason
- * every other block needs one present key.
- *
- * Defensive like the rest: a non-map is returned untouched for validate
- * to reject by path. */
 function normfeatures(f: any): any {
   if (!ismap(f)) { return f }
   const out: any = {}
@@ -152,32 +105,11 @@ const CREDENTIAL_KEYS = [
   'secret', 'password', 'credential', 'bearer',
 ]
 
-/** The suffix rule catches `access_key`, `X-Api-Token` and friends in
- * one rule rather than a growing list of spellings. */
 const CREDENTIAL_SUFFIX = ['_KEY', '_TOKEN', '_SECRET', '_PASSWORD']
 
-/** §5.2's backstop, and it is stated as one rather than as a grammar.
- * `validname()` is a NAME grammar, not a credential filter: it rejects
- * uppercase, hyphens, `+`, `/` and `=`, so it excludes most real
- * credential formats - but a lowercase hex token passes it cleanly. A
- * character class cannot tell a name from a secret.
- *
- * Derived names break on every separator (`voxgig_solardemo.apikey`
- * runs 6/9/6) and a hand-written name for a human to read does too; a
- * 24-character unbroken run is not a name anybody writes. Note this is
- * a RUN bound, not a length bound: `acme_internal_billing_service.apikey`
- * is 36 characters and passes, which is the false positive a naive
- * length bound would produce. */
 const RUN_BOUND = 24
 const UNBROKEN_RUN = new RegExp('[A-Za-z0-9]{' + RUN_BOUND + ',}')
 
-/** Normalize, then validate (§4.2). Raises `station_config_invalid`
- * with EVERY struct error at once - an eighteen-instance config that
- * touches three of them must not die because the eighteenth has a
- * typo'd package name - then the §5.2 scans.
- *
- * Takes the NORMALIZED form. Handing it a raw config is the mistake
- * §4.2 exists to prevent, so callers go through open()/loadConfig. */
 export function validateConfig(normalized: any): any {
   const errs: string[] = []
   validate(normalized, configShape(), { errs })
@@ -190,11 +122,6 @@ export function validateConfig(normalized: any): any {
   return normalized
 }
 
-/** `plugin` is REMOVED, not aliased (§3.4) - a deprecated alias would
- * be a second grammar for one concept in 17 ports. The shape already
- * rejects it as an unexpected key; this says what to rename, because
- * "unexpected key: plugin" alone does not, and the migration for a
- * single-instance project is exactly this one rename. */
 function renamehint(cfg: any): string {
   const profiles = ismap(cfg) && ismap(cfg.profiles) ? cfg.profiles : {}
   const hit = Object.keys(profiles)
@@ -205,8 +132,6 @@ function renamehint(cfg: any): string {
     ' - the keys are unchanged, an untagged ref IS an api slug (§3.4)'
 }
 
-/** The §5.2 scans, over the parts of the grammar that hold arbitrary
- * data. Everything else is closed by construction and needs no scan. */
 function scanConfig(cfg: any): void {
   const secrets: string[] = []
   const reserved: string[] = []
@@ -234,15 +159,9 @@ function scanConfig(cfg: any): void {
           secretvalue(block.secret, bpath + '.secret', secrets)
         }
 
-        // `options` is passthrough to a generated constructor, so it is
-        // the one place a value can hide.
         scan(block.options, bpath + '.options', secrets, reserved)
         checkfeatures(block.feature, bpath + '.feature', secrets, reserved, invalid)
 
-        // §4.4's explicit checks, applied where the shape cannot reach,
-        // raising the same code the shape would - and pinned in the
-        // corpus so each workaround is removed deliberately when struct
-        // is fixed rather than forgotten.
         checkpolicy(block.policy, bpath + '.policy', invalid)
       }
     }
@@ -282,19 +201,6 @@ function checkfeatures(
   }
 }
 
-/** The policy block's §4.4 workarounds, in one place because they are
- * one class of gap: struct cannot check what its own defects hide.
- *
- * - `hosts`, `allow.op` and `allow.method` are `$CHILD` string lists,
- *   so element 0 escapes the shape (see firstelement below).
- * - `budget` is a map whose keys are ALL optional scalars, and struct
- *   removes an unsatisfied optional key from the spec node - so
- *   `budget: {rp: 1}` degenerates the spec into an open map and the
- *   typo passes. `allow` does not have this problem (its `$CHILD` keys
- *   stay in the spec whether or not the data carries them, keeping the
- *   map closed), and neither does `policy` itself (`hosts` anchors it);
- *   `budget` alone needs the explicit unexpected-key check, phrased as
- *   struct would phrase it. */
 const BUDGET_KEYS = ['concurrency', 'rps']
 
 function checkpolicy(policy: any, path: string, invalid: string[]): void {
@@ -319,19 +225,6 @@ function checkpolicy(policy: any, path: string, invalid: string[]): void {
   }
 }
 
-/** §4.4: `$CHILD` in list mode DOES NOT VALIDATE ELEMENT 0. Verified:
- * `["a", 1]` fails at index 1, `[1]` passes. validate_CHILD installs the
- * template across the data's indices, sets keyI = 0 and returns element
- * 0 as the slot value, and the injection loop resumes past it. An
- * upstream struct defect; filing it is a deliverable of this plan.
- *
- * It reaches EVERY string list in the shape. §4.4 says the only one left
- * is `policy.hosts` because the profile-level `order` list is gone - but
- * §8.4's per-feature `order` carries `before`/`after` string lists, so
- * the reach is three lists, not one, and §4.5 pins `order: [7]`
- * accordingly. Applied where the shape cannot reach, raising the same
- * code the shape would, and pinned in the corpus so the workaround is
- * removed deliberately when struct is fixed rather than forgotten. */
 function firstelement(list: any, path: string, invalid: string[]): void {
   if (!Array.isArray(list) || 0 === list.length) { return }
   if ('string' === typeof list[0]) { return }
@@ -357,8 +250,6 @@ function scan(
     const kpath = path + '.' + key
     const val = node[key]
 
-    // §8.6: station owns feature composition, so an `options.feature`
-    // in a declarative config is a second, unreconciled ordering input.
     if ('feature' === key) {
       reserved.push(kpath + ' is reserved: configure features under the ' +
         'block\'s own `feature` key, not through `options`')
@@ -387,10 +278,6 @@ function credentialkey(key: string): boolean {
   return CREDENTIAL_SUFFIX.some((s) => tok.endsWith(s))
 }
 
-/** A `secret`-named key holds a NAME, and that exemption is not a
- * loophole - it is the whole design. Two checks, not one, and they live
- * in the same three lines precisely so a port cannot implement only the
- * first and inherit the gap the second exists to close. */
 function secretvalue(val: any, path: string, secrets: string[]): void {
   if ('string' !== typeof val) {
     secrets.push(path + ' must be a secret name (a string), but found ' +

package/src/types.ts

@@ -6,18 +6,10 @@ export type StationOptions = {
   proxy?: 'auto' | 'off' | 'require' | string
   folder?: string
   config?: StationConfig | null
-  // §6.3: disables the loader outright. Only self-registered and
-  // explicitly provided factories are used.
   load?: boolean
-  // Set when the config came from ~/.voxgig/station.json rather than
-  // from inside the repo. A user-level file is outside the repo's
-  // review boundary, so a `package` key arriving from it is IGNORED
-  // WITH A WARNING rather than imported - everything else in it still
-  // applies.
   repoScoped?: boolean
 }
 
-// station.json shape (profiles carry sekreto ProviderSpecs verbatim).
 export type StationConfig = {
   station: number
   profiles?: Record<string, Profile>
@@ -26,28 +18,10 @@ export type StationConfig = {
 export type Profile = {
   secrets?: { providers?: any[] }
   feature?: Record<string, any>
-  // Keyed by api slug: defaults inherited by every instance of that
-  // api, declaring no instance of its own (design §3.1).
   api?: Record<string, SdkBlock>
-  // Keyed by REF (`api$tag`, or bare `api` for the untagged instance).
-  // This replaces `plugin`, which is REMOVED rather than aliased (§3.4)
-  // - a deprecated alias would be a second grammar for one concept in
-  // 17 ports. An untagged ref is an api slug, so every existing block
-  // means exactly what it meant before under the new key.
   sdk?: Record<string, SdkBlock>
 }
 
-// The same key set in both block positions. The two differ in what
-// they KEY, not in what they hold, which is why the two spec objects in
-// config-shape.json are identical and a guard test asserts it (§3.1).
-// Per-plugin policy (design §16). The solo-expressible keys:
-// `hosts` and `mode` gate the operation path in the library; `allow`
-// is set into the SDK's own `options.allow` so enforcement rides the
-// SDK's own pipeline; `budget` configures the SDK's `ratelimit`
-// feature through the ordinary feature composition. `record`,
-// `replay` and `mock` are proxy-era vocabulary, accepted now so a
-// config written for the proxy is not a validation error, and failing
-// `station_no_proxy` on the operation path until one is attached.
 export type PolicyBlock = {
   hosts?: string[]
   allow?: { op?: string[], method?: string[] }
@@ -62,13 +36,6 @@ export type SdkBlock = {
   secret?: string
   resolve?: 'library' | 'proxy'
   policy?: PolicyBlock
-  // Read by the PROXY out of this very file (design §8.3: the proxy
-  // loads profiles ITSELF): the capture depth it records this
-  // instance's exchanges at (§8.5), and §16's per-instance agent write
-  // opt-in, which a mutating agent operation needs alongside the
-  // daemon's own --agent-write flag. They belong to the SHARED shape
-  // because one station.json serves both the application and the
-  // proxy; a shape that rejected them would make that impossible.
   capture?: 'meta' | 'headers' | 'full'
   agent?: { write: boolean }
   feature?: Record<string, any>
@@ -80,8 +47,6 @@ export type SdkBlock = {
   active?: boolean
 }
 
-// Descriptor v1 (design §4): a view over the SDK's embedded config,
-// normalized - never a second model.
 export type Descriptor = {
   station: 1
   name: string
@@ -114,15 +79,9 @@ export type DescriptorPoint = {
   select?: Record<string, any>
 }
 
-// StationEvent v1 (design §6). Unknown fields are ignored by consumers.
 export type StationEvent = {
   t: number
-  // The INSTANCE name (§7.3). Keeps its name, so a consumer that only
-  // knows `plugin` keeps working - it simply sees instance-grained
-  // events, which is what it wants at 20 SDKs anyway.
   plugin?: string
-  // The api slug, for grouping. ADDITIVE, so station.md §8.6's wire
-  // compatibility rule holds.
   api?: string
   corr?: string
   kind: 'construct' | 'op' | 'http' | 'error' | 'feature' | 'station'
@@ -135,50 +94,32 @@ export type StationEvent = {
   meta?: Record<string, any>
 }
 
-// What registration hands back to the adapter (design §3 item 1).
 export type Binding = {
   // The INSTANCE name (a ref). Keeps the field name for wire
   // compatibility - a consumer that only knows `plugin` keeps working
   // and simply sees instance-grained bindings (§7.3).
   plugin: string
-  // The api slug, for grouping. Additive.
   instance?: string
   base?: string
   placeholder?: string
-  // The instance's EFFECTIVE secret name, and the authority for it
-  // (§7.4). A descriptor is shared by every instance of one api and so
-  // cannot hold two different instance-derived names; the descriptor's
-  // own `auth.secretname` stays the api-level default, which is
-  // documentation.
   secretname?: string
   rung: 'none' | 'R1'
 }
 
 export type PluginEntry = {
-  // The instance name - the registry key (§7.1).
   name: string
-  // The api slug. One descriptor per api is shared by every instance of
-  // it, so this is what `descriptorOf` and the cache key on.
   api: string
   descriptor: Descriptor
   rung: 'none' | 'R1'
   client: any
   warnings: string[]
-  // The instance's effective secret name, mirroring Binding.secretname
-  // so `plugins()` can report it without re-deriving.
   secretname?: string
 }
 
-// A declared instance, resolved (§6.1's `instances()`).
 export type ResolvedInstance = {
   name: string
   api: string
-  // `active: false` means BARRED FROM RUNNING - declared, visible, and
-  // refused a client. Not a runtime state.
   active: boolean
-  // Exactly plugin's `status == "live"`; the two answer different
-  // questions and the answers differ routinely, since a lazily-started
-  // instance is active and not yet live.
   live: boolean
   rung: 'none' | 'R1'
   block: SdkBlock