@voxgig/station 0.0.1

package/dist/src/descriptor.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envtoken = envtoken;
+exports.secretnameDefault = secretnameDefault;
+exports.normalizeDescriptor = normalizeDescriptor;
+exports.canonicalSerialize = canonicalSerialize;
+// The ONLY way to build an env-var token in station, mirroring sdkgen's
+// packageMeta envToken exactly: 'gnarly-pets' -> 'GNARLY_PETS'. The
+// `secretname` corpus section pins the round-trip against sekreto's
+// envkey() and sdkgen's envName() - the one place three grammars meet.
+function envtoken(name) {
+    return String(name || '')
+        .toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+// The default sekreto name for a plugin (design §5.1): envtoken(slug)
+// lowercased, plus '.apikey'. sekreto's envkey() then yields exactly the
+// env var the SDK's README documents: gnarly_pets.apikey -> GNARLY_PETS_APIKEY.
+function secretnameDefault(slug) {
+    return envtoken(slug).toLowerCase() + '.apikey';
+}
+// Best-effort slug from a camel name, for SDKs whose embedded config
+// predates main.slug (design §4 legacy sentinels). The hyphen caveat is
+// real: 'VoxgigSolardemo' -> 'voxgigsolardemo', NOT 'voxgig-solardemo' -
+// callers surface a warning event when this path is taken.
+function legacySlug(name) {
+    return String(name || '').toLowerCase();
+}
+// Normalize a generated SDK's embedded config into descriptor v1
+// (design §4). The config is the one every SDK carries (Config.main /
+// .feature / .options / .entity); the descriptor is a VIEW over it.
+// Returns the descriptor plus any legacy warnings.
+function normalizeDescriptor(config, activeFeatures) {
+    const warnings = [];
+    const main = config?.main || {};
+    const options = config?.options || {};
+    const name = String(main.name || '');
+    let slug = main.slug;
+    if (null == slug || '' === slug) {
+        slug = legacySlug(name);
+        warnings.push('descriptor: legacy config has no main.slug; derived "' +
+            slug + '" from the camel name - hyphens in the original name are lost');
+    }
+    const version = null != main.version ? String(main.version) : '0.0.0';
+    const target = null != main.target ? String(main.target) : 'unknown';
+    const server = [];
+    const svr = options.server || {};
+    for (const k of Object.keys(svr).sort()) {
+        server.push({ name: k, value: String(svr[k]) });
+    }
+    const authActive = null != options.auth;
+    const auth = {
+        active: authActive,
+        prefix: authActive ? String(options.auth.prefix || '') : '',
+        secretname: secretnameDefault(slug),
+    };
+    const entities = {};
+    const entdefs = config?.entity || {};
+    for (const ename of Object.keys(entdefs).sort()) {
+        const e = entdefs[ename] || {};
+        const fields = {};
+        for (const f of e.fields || []) {
+            if (null != f && null != f.name) {
+                fields[f.name] = { kind: String(f.kind || f.type || '') };
+            }
+        }
+        const ops = {};
+        const opdefs = e.op || {};
+        for (const opname of Object.keys(opdefs).sort()) {
+            const op = opdefs[opname] || {};
+            const points = [];
+            for (const p of op.points || []) {
+                if (null == p) {
+                    continue;
+                }
+                const point = {
+                    method: String(p.method || ''),
+                    path: String(p.orig || p.path || ''),
+                    params: (p.parts || []).filter((s) => 'string' === typeof s &&
+                        s.startsWith(':')).map((s) => s.slice(1)),
+                };
+                if (null != p.select) {
+                    point.select = p.select;
+                }
+                points.push(point);
+            }
+            ops[opname] = { points };
+        }
+        entities[ename] = { fields, ops };
+    }
+    // §7.4: the features list gains `options` and `transport`, because
+    // it was throwing away what the SDK already embeds -
+    // `config.feature[name].options` is the feature's own declared key
+    // set WITH TYPED DEFAULTS, which is the schema §8.5 validates
+    // against, and `transport` is the role §8.4 orders by.
+    //
+    // Both are already inside the SDK; the descriptor stops discarding
+    // them. ADDITIVE, so descriptor v1 consumers are unaffected.
+    //
+    // `transport` is carried rather than inferred: the obvious signal, an
+    // empty `hook: {}`, is wrong for station, which both wraps AND
+    // dispatches hooks. Absent until sdkgen emits it (§11 items 6-7), and
+    // §8.4's role checks degrade to nothing until then rather than
+    // guessing.
+    const features = [];
+    const fdefs = config?.feature || {};
+    const factive = activeFeatures || {};
+    for (const fname of Object.keys(fdefs).sort()) {
+        const fdef = fdefs[fname] || {};
+        const row = { name: fname, active: true === factive[fname]?.active };
+        if (null != fdef.options && 'object' === typeof fdef.options) {
+            row.options = fdef.options;
+        }
+        if (null != fdef.transport && '' !== fdef.transport) {
+            row.transport = String(fdef.transport);
+        }
+        features.push(row);
+    }
+    const descriptor = {
+        station: 1,
+        name, slug,
+        envtoken: envtoken(slug),
+        version, target,
+        base: String(options.base || ''),
+        server, auth, entities, features,
+    };
+    return { descriptor, warnings };
+}
+// Canonical serialization (design §4): UTF-8, object keys sorted
+// bytewise, no insignificant whitespace, minimal JSON escaping. The
+// proxy dedupes registrations by a hash of this, so every language must
+// produce identical bytes - the `canonical-serialize` corpus section
+// carries the adversarial cases.
+//
+// The bytewise sort compares UTF-8 BYTE SEQUENCES, not UTF-16 code
+// units, through TextEncoder rather than Buffer: TextEncoder is a
+// standard global in Node and every browser, so this module stays on
+// the browser entry's import graph (§2.2, §17 Phase 1) with no node:
+// dependency. Uint8Array elements are unsigned bytes, so plain numeric
+// comparison IS the bytewise order Buffer.compare gave - the corpus'
+// non-ASCII sort case pins the equivalence.
+const UTF8 = new TextEncoder();
+function bytecompare(a, b) {
+    const ab = UTF8.encode(a), bb = UTF8.encode(b);
+    const n = ab.length < bb.length ? ab.length : bb.length;
+    for (let i = 0; i < n; i++) {
+        if (ab[i] !== bb[i]) {
+            return ab[i] - bb[i];
+        }
+    }
+    return ab.length - bb.length;
+}
+function canonicalSerialize(value) {
+    if (null === value || 'boolean' === typeof value || 'number' === typeof value) {
+        return JSON.stringify(value);
+    }
+    if ('string' === typeof value) {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalSerialize).join(',') + ']';
+    }
+    if ('object' === typeof value) {
+        const keys = Object.keys(value).filter((k) => undefined !== value[k]);
+        // Bytewise sort: compare UTF-8 byte sequences, not UTF-16 code units.
+        keys.sort(bytecompare);
+        return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalSerialize(value[k])).join(',') + '}';
+    }
+    return 'null';
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/src/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.js","sourceRoot":"","sources":["../../src/descriptor.ts"],"names":[],"mappings":"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"}

package/dist/src/error.d.ts

@@ -0,0 +1,8 @@
+declare const CODES: readonly ["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", "station_config_invalid", "station_config_secret", "station_secret_collision", "station_feature_reserved", "station_instance_api", "station_no_instance", "station_instance_inactive", "station_sdk_load", "station_no_factory", "station_factory_conflict", "station_feature_unknown", "station_feature_option", "station_feature_order"];
+export type StationErrorCode = typeof CODES[number];
+export declare class StationError extends Error {
+    code: StationErrorCode;
+    constructor(code: StationErrorCode, message: string);
+}
+export declare function isKnownCode(code: string): boolean;
+export {};

package/dist/src/error.js

@@ -0,0 +1,60 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StationError = void 0;
+exports.isKnownCode = isKnownCode;
+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',
+];
+class StationError extends Error {
+    constructor(code, message) {
+        super(code + ': ' + message);
+        this.name = 'StationError';
+        this.code = code;
+    }
+}
+exports.StationError = StationError;
+function isKnownCode(code) {
+    return CODES.includes(code);
+}
+//# sourceMappingURL=error.js.map

package/dist/src/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/error.ts"],"names":[],"mappings":";AAAA,2DAA2D;AAC3D,iEAAiE;AACjE,sDAAsD;;;AA2DtD,kCAEC;AA3DD,MAAM,KAAK,GAAG;IACZ,kBAAkB;IAClB,yBAAyB;IACzB,sBAAsB;IACtB,qBAAqB;IACrB,oBAAoB;IACpB,uBAAuB;IACvB,oBAAoB;IACpB,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,eAAe;IACf,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;IACtB,uBAAuB;IACvB,qBAAqB;IAErB,mEAAmE;IACnE,sEAAsE;IACtE,qEAAqE;IACrE,oEAAoE;IACpE,wBAAwB;IACxB,wBAAwB;IACxB,uBAAuB;IACvB,0BAA0B;IAC1B,0BAA0B;IAE1B,sEAAsE;IACtE,gDAAgD;IAChD,sBAAsB;IACtB,qBAAqB;IACrB,2BAA2B;IAC3B,kBAAkB;IAClB,oBAAoB;IACpB,0BAA0B;IAE1B,sEAAsE;IACtE,mEAAmE;IACnE,kDAAkD;IAClD,yBAAyB;IACzB,wBAAwB;IACxB,uBAAuB;CACf,CAAA;AAIV,MAAa,YAAa,SAAQ,KAAK;IAGrC,YAAY,IAAsB,EAAE,OAAe;QACjD,KAAK,CAAC,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AARD,oCAQC;AAED,SAAgB,WAAW,CAAC,IAAY;IACtC,OAAQ,KAA2B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;AACpD,CAAC"}

package/dist/src/events.d.ts

@@ -0,0 +1,15 @@
+import { StationEvent } from './types';
+export declare class EventBuffer {
+    private ring;
+    private max;
+    private drops;
+    private taps;
+    constructor(max?: number);
+    emit(ev: StationEvent): void;
+    events(): StationEvent[];
+    tap(fn: (ev: StationEvent) => void): () => void;
+    status(): {
+        buffered: number;
+        dropped: number;
+    };
+}

package/dist/src/events.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBuffer = void 0;
+// 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().
+class EventBuffer {
+    constructor(max) {
+        this.ring = [];
+        this.drops = 0;
+        this.taps = [];
+        this.max = null == max ? 1000 : max;
+    }
+    emit(ev) {
+        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() {
+        return this.ring.slice();
+    }
+    tap(fn) {
+        this.taps.push(fn);
+        return () => {
+            const i = this.taps.indexOf(fn);
+            if (-1 !== i) {
+                this.taps.splice(i, 1);
+            }
+        };
+    }
+    status() {
+        return { buffered: this.ring.length, dropped: this.drops };
+    }
+}
+exports.EventBuffer = EventBuffer;
+//# sourceMappingURL=events.js.map

package/dist/src/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":";;;AAEA,wEAAwE;AACxE,0EAA0E;AAC1E,0DAA0D;AAE1D,MAAa,WAAW;IAMtB,YAAY,GAAY;QALhB,SAAI,GAAmB,EAAE,CAAA;QAEzB,UAAK,GAAG,CAAC,CAAA;QACT,SAAI,GAAmC,EAAE,CAAA;QAG/C,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAA;IACrC,CAAC;IAED,IAAI,CAAC,EAAgB;QACnB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAClB,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAA;YACjB,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;QACD,kEAAkE;QAClE,qBAAqB;QACrB,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC;gBAAC,EAAE,CAAC,EAAE,CAAC,CAAA;YAAC,CAAC;YAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAA;IAC1B,CAAC;IAED,GAAG,CAAC,EAA8B;QAChC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAClB,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;YAC/B,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YAAC,CAAC;QAC1C,CAAC,CAAA;IACH,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,CAAA;IAC5D,CAAC;CACF;AAtCD,kCAsCC"}

package/dist/src/factory.d.ts

@@ -0,0 +1,24 @@
+export type Factory = {
+    construct: (options: any) => any;
+    config: any;
+};
+export type FactoryEntry = {
+    api: string;
+    construct: (options: any) => any;
+    config: any;
+    descriptor: any;
+    warnings: string[];
+};
+/** 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 declare function provide(api: string, factory: Factory): FactoryEntry;
+export declare function factoryFor(api: string): FactoryEntry | undefined;
+export declare function provided(): string[];
+/** 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 declare function resetFactories(): void;

package/dist/src/factory.js

@@ -0,0 +1,79 @@
+"use strict";
+/* 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. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provide = provide;
+exports.factoryFor = factoryFor;
+exports.provided = provided;
+exports.resetFactories = resetFactories;
+const error_1 = require("./error");
+const descriptor_1 = require("./descriptor");
+const TABLE = new Map();
+/** 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. */
+function provide(api, factory) {
+    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 error_1.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 } = (0, descriptor_1.normalizeDescriptor)(factory.config, undefined);
+    const entry = {
+        api: slug,
+        construct: factory.construct,
+        config: factory.config,
+        descriptor,
+        warnings,
+    };
+    TABLE.set(slug, entry);
+    return entry;
+}
+function factoryFor(api) {
+    return TABLE.get(String(api));
+}
+function provided() {
+    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. */
+function resetFactories() {
+    TABLE.clear();
+}
+//# sourceMappingURL=factory.js.map

package/dist/src/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;sEA2BsE;;AA2BtE,0BAwBC;AAED,gCAEC;AAED,4BAEC;AAID,wCAEC;AA/DD,mCAAsC;AACtC,6CAAkD;AAelD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAwB,CAAA;AAE7C;;;;;;0EAM0E;AAC1E,SAAgB,OAAO,CAAC,GAAW,EAAE,OAAgB;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC7B,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;QAClB,IAAI,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;YAC7E,OAAO,KAAK,CAAA;QACd,CAAC;QACD,MAAM,IAAI,oBAAY,CAAC,0BAA0B,EAC/C,8CAA8C,GAAG,IAAI,GAAG,OAAO;YAC/D,2DAA2D;YAC3D,uCAAuC,CAAC,CAAA;IAC5C,CAAC;IAED,kEAAkE;IAClE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAA,gCAAmB,EAAC,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC/E,MAAM,KAAK,GAAiB;QAC1B,GAAG,EAAE,IAAI;QACT,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU;QACV,QAAQ;KACT,CAAA;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACtB,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAgB,UAAU,CAAC,GAAW;IACpC,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;AAC/B,CAAC;AAED,SAAgB,QAAQ;IACtB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;AACxC,CAAC;AAED;iEACiE;AACjE,SAAgB,cAAc;IAC5B,KAAK,CAAC,KAAK,EAAE,CAAA;AACf,CAAC"}

package/dist/src/feature.d.ts

@@ -0,0 +1,106 @@
+/** Reserved on a feature entry: not options, and never passed through
+ * to the SDK's own option map. */
+export declare const RESERVED_KEYS: string[];
+/** 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 declare function mergefeatures(sources: any[]): {
+    [name: string]: any;
+};
+/** 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 declare function featuresources(base: any, overlay: any, api: string, ref: string): any[];
+/** `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 declare const BAND_DEFAULT = 0;
+export declare const BAND_STATION = 100;
+export declare const BAND_TEST = 200;
+/** Higher is further IN. */
+export declare function defaultband(name: string): number;
+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 declare function resolveorder(merged: {
+    [name: string]: any;
+}): Ordered[];
+/** 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 declare function checkpin(ordered: Ordered[]): void;
+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 declare function checkfeatures(merged: {
+    [name: string]: any;
+}, descriptor: any): FeatureFault[];
+/** 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 declare function composefeatures(ordered: Ordered[]): any[];