@browsercore/testing 0.1.0

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @browsercore/testing — public API surface.
+ *
+ * Protocol verification: RFC compliance tests, browser golden packet captures,
+ * integration tests, and benchmarking.
+ */
+export { loadGolden, compareAgainstGolden } from "./golden/golden.js";
+export { runTlsCompliance, runHttp2Compliance, runHttp1Compliance } from "./rfc/rfcTests.js";
+export { benchmarkTlsHandshake, benchmarkHttp2Request } from "./bench/bench.js";
+export { GoldenMismatchError, TestingError } from "./errors.js";
+export { assertNever, bytesToHex, compareBytes, createId } from "./utils.js";
+// Test-category model (docs/TEST-SUITE.md) + the 17 vitest suite ids.
+export { TestCategory } from "./types.js";
+export * as categories from "./categories/index.js";
+// Randomized-field comparison (Cat 14 core) + capture manifest.
+export { compareBytesWithIgnore } from "./utils.js";
+export { captures } from "./captures/manifest.js";
+// Pluggable layered reference provider.
+export { createReferenceProvider, CurlImpersonateProvider, RealBrowserCaptureProvider, } from "./reference/reference.js";
+// Fingerprint computation (JA3 / JA4) for Cat 4.
+export { computeJa3, computeJa4, Ja3ParseError, parseClientHello } from "./fingerprint/index.js";
+// Node.js reference oracle — deterministic comparison target for the primitive
+// layers (crypto, dns, zlib, wire format). See src/reference/node-reference.ts.
+export { nodeCrypto, nodeDns, nodeZlib, nodeHttp, toError, compareBytesOutcome, } from "./reference/node-reference.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAEhF,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAchE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE7E,sEAAsE;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AAEpD,gEAAgE;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAqB,MAAM,wBAAwB,CAAC;AAErE,wCAAwC;AACxC,OAAO,EACH,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,GAC7B,MAAM,0BAA0B,CAAC;AASlC,iDAAiD;AACjD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAGjG,+EAA+E;AAC/E,gFAAgF;AAChF,OAAO,EACH,UAAU,EACV,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,mBAAmB,GACtB,MAAM,+BAA+B,CAAC"}

package/dist/reference/node-reference.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Node.js reference oracle.
+ *
+ * Wraps Node's built-in implementations (node:crypto, node:zlib, node:dns,
+ * node:net, node:http, node:http2, node:tls) behind a uniform comparator surface
+ * so our @browsercore/* packages can be tested for EQUIVALENT observable behavior.
+ *
+ * Design rule: we compare against Node only for LAYERS WHERE NODE IS THE SPEC
+ * REFERENCE — crypto primitives, DNS resolution, compression, and wire-format
+ * serialization. We deliberately do NOT compare browser-fingerprint layers
+ * (TLS ClientHello, HTTP/2 SETTINGS, default headers) against Node, because the
+ * whole point of this project is to diverge from Node to match browsers. Those
+ * are validated against browser golden captures elsewhere.
+ *
+ * Every method returns Node Buffer/values that our tests convert to Uint8Array
+ * for comparison with our packages' Uint8Array-centric APIs.
+ */
+import { constants as zlibConstants } from "node:zlib";
+/** Which hash algorithm a primitive uses — branded union, no magic strings. */
+export type HashAlgorithm = "sha256" | "sha384";
+/** Validated HKDF/hash helpers that mirror the @browsercore/crypto interface. */
+export declare const nodeCrypto: {
+    /** SHA-256 digest. Equivalent oracle for our `crypto.sha256`. */
+    readonly sha256: (data: Uint8Array) => Uint8Array;
+    /** SHA-384 digest. Equivalent oracle for our `crypto.sha384`. */
+    readonly sha384: (data: Uint8Array) => Uint8Array;
+    /**
+     * HKDF extract+expand per RFC 5869. Equivalent oracle for our `crypto.hkdf`.
+     * Uses node:crypto.hkdfSync under the hood.
+     */
+    readonly hkdf: (algorithm: HashAlgorithm, salt: Uint8Array, ikm: Uint8Array, info: Uint8Array, length: number) => Uint8Array;
+    /** HMAC. Equivalent oracle for our `crypto.hmac`. */
+    readonly hmac: (algorithm: HashAlgorithm, key: Uint8Array, data: Uint8Array) => Uint8Array;
+    /** Cryptographically secure random bytes (length oracle). */
+    readonly randomBytes: (length: number) => Uint8Array;
+    /** Expected digest length for a given hash algorithm. */
+    readonly digestLength: (algorithm: HashAlgorithm) => number;
+};
+/** DNS resolution oracle (mirrors our `resolveHost`). */
+export declare const nodeDns: {
+    /** Resolve a host to an address, matching our `resolveHost` semantics. */
+    readonly lookup: (host: string, ipv6: boolean) => Promise<{
+        readonly address: string;
+        readonly family: 4 | 6;
+    }>;
+};
+/** Compression oracle (mirrors the future @browsercore/compression interface). */
+export declare const nodeZlib: {
+    readonly gzip: (data: Uint8Array) => Uint8Array;
+    readonly gunzip: (data: Uint8Array) => Uint8Array;
+    readonly deflate: (data: Uint8Array) => Uint8Array;
+    readonly inflate: (data: Uint8Array) => Uint8Array;
+    readonly brotliCompress: (data: Uint8Array) => Uint8Array;
+    readonly brotliDecompress: (data: Uint8Array) => Uint8Array;
+    /** The zlib window bits constant, for comparing deflate framing decisions. */
+    readonly zlibConstants: typeof zlibConstants;
+};
+/**
+ * Wire-format oracle for HTTP/1.1. Node's `http` module is the de-facto
+ * reference for the on-the-wire request/response format (RFC 7230). We use it
+ * to assert our serializer/parser produce bytes Node would accept and generate
+ * the same wire layout.
+ */
+export declare const nodeHttp: {
+    /**
+     * Build the request-line + headers block exactly as Node's http client would
+     * serialize them, so we can compare against our `serializeRequest`.
+     * Body is appended verbatim by the caller.
+     */
+    readonly serializeRequestLineAndHeaders: (method: string, url: string, headers: ReadonlyMap<string, string>) => Uint8Array;
+};
+/** Narrow an unknown thrown value to an Error (mirrors transport.ensure*). */
+export declare function toError(e: unknown): Error;
+/** Discriminated result of a reference comparison. */
+export type CompareOutcome = {
+    readonly equal: true;
+} | {
+    readonly equal: false;
+    readonly reason: string;
+};
+/** Generic byte-level comparison returning a discriminated outcome. */
+export declare function compareBytesOutcome(a: Uint8Array, b: Uint8Array): CompareOutcome;
+//# sourceMappingURL=node-reference.d.ts.map

package/dist/reference/node-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-reference.d.ts","sourceRoot":"","sources":["../../src/reference/node-reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,EAA4B,SAAS,IAAI,aAAa,EAAE,MAAM,WAAW,CAAC;AAqBjF,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAGhD,iFAAiF;AACjF,eAAO,MAAM,UAAU;IACnB,iEAAiE;4BACpD,UAAU,KAAG,UAAU;IAIpC,iEAAiE;4BACpD,UAAU,KAAG,UAAU;IAIpC;;;OAGG;+BAEY,aAAa,QAClB,UAAU,OACX,UAAU,QACT,UAAU,UACR,MAAM,KACf,UAAU;IAOb,qDAAqD;+BACrC,aAAa,OAAO,UAAU,QAAQ,UAAU,KAAG,UAAU;IAK7E,6DAA6D;mCACzC,MAAM,KAAG,UAAU;IAIvC,yDAAyD;uCACjC,aAAa,KAAG,MAAM;CAGxC,CAAC;AAEX,yDAAyD;AACzD,eAAO,MAAM,OAAO;IAChB,0EAA0E;4BAEhE,MAAM,QACN,OAAO,KACd,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;KAAE,CAAC;CAY1D,CAAC;AAEX,kFAAkF;AAClF,eAAO,MAAM,QAAQ;0BACN,UAAU,KAAG,UAAU;4BAGrB,UAAU,KAAG,UAAU;6BAGtB,UAAU,KAAG,UAAU;6BAGvB,UAAU,KAAG,UAAU;oCAGhB,UAAU,KAAG,UAAU;sCAGrB,UAAU,KAAG,UAAU;IAG9C,8EAA8E;4BACzD,OAAO,aAAa;CAGnC,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,QAAQ;IACjB;;;;OAIG;sDAES,MAAM,OACT,MAAM,WACF,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KACrC,UAAU;CAQP,CAAC;AAEX,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAKzC;AAED,sDAAsD;AACtD,MAAM,MAAM,cAAc,GACpB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,cAAc,CAUhF"}

package/dist/reference/node-reference.js

@@ -0,0 +1,161 @@
+/**
+ * Node.js reference oracle.
+ *
+ * Wraps Node's built-in implementations (node:crypto, node:zlib, node:dns,
+ * node:net, node:http, node:http2, node:tls) behind a uniform comparator surface
+ * so our @browsercore/* packages can be tested for EQUIVALENT observable behavior.
+ *
+ * Design rule: we compare against Node only for LAYERS WHERE NODE IS THE SPEC
+ * REFERENCE — crypto primitives, DNS resolution, compression, and wire-format
+ * serialization. We deliberately do NOT compare browser-fingerprint layers
+ * (TLS ClientHello, HTTP/2 SETTINGS, default headers) against Node, because the
+ * whole point of this project is to diverge from Node to match browsers. Those
+ * are validated against browser golden captures elsewhere.
+ *
+ * Every method returns Node Buffer/values that our tests convert to Uint8Array
+ * for comparison with our packages' Uint8Array-centric APIs.
+ */
+import { createHash, createHmac, hkdfSync, randomBytes } from "node:crypto";
+import { gunzipSync, gzipSync, brotliCompressSync, brotliDecompressSync } from "node:zlib";
+import { lookup as dnsLookup } from "node:dns";
+import { deflateSync, inflateSync, constants as zlibConstants } from "node:zlib";
+import { assertNever } from "../utils.js";
+/** Normalize a Node Buffer / Uint8Array / readonly Uint8Array to a fresh Uint8Array. */
+function toBytes(data) {
+    return new Uint8Array(data);
+}
+/** Compare two byte arrays for equality (helper for one-off oracle checks). */
+function bytesEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+const HASH_LENGTHS = { sha256: 32, sha384: 48 };
+/** Validated HKDF/hash helpers that mirror the @browsercore/crypto interface. */
+export const nodeCrypto = {
+    /** SHA-256 digest. Equivalent oracle for our `crypto.sha256`. */
+    sha256(data) {
+        return toBytes(createHash("sha256").update(data).digest());
+    },
+    /** SHA-384 digest. Equivalent oracle for our `crypto.sha384`. */
+    sha384(data) {
+        return toBytes(createHash("sha384").update(data).digest());
+    },
+    /**
+     * HKDF extract+expand per RFC 5869. Equivalent oracle for our `crypto.hkdf`.
+     * Uses node:crypto.hkdfSync under the hood.
+     */
+    hkdf(algorithm, salt, ikm, info, length) {
+        const algo = algorithm === "sha256" ? "sha256" : "sha384";
+        return toBytes(hkdfSync(algo, ikm, salt, info, length));
+    },
+    /** HMAC. Equivalent oracle for our `crypto.hmac`. */
+    hmac(algorithm, key, data) {
+        const algo = algorithm === "sha256" ? "sha256" : "sha384";
+        return toBytes(createHmac(algo, key).update(data).digest());
+    },
+    /** Cryptographically secure random bytes (length oracle). */
+    randomBytes(length) {
+        return toBytes(randomBytes(length));
+    },
+    /** Expected digest length for a given hash algorithm. */
+    digestLength(algorithm) {
+        return HASH_LENGTHS[algorithm];
+    },
+};
+/** DNS resolution oracle (mirrors our `resolveHost`). */
+export const nodeDns = {
+    /** Resolve a host to an address, matching our `resolveHost` semantics. */
+    async lookup(host, ipv6) {
+        return new Promise((resolve, reject) => {
+            const options = { family: ipv6 ? 6 : 4 };
+            dnsLookup(host, options, (err, address, family) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                resolve({ address, family: family });
+            });
+        });
+    },
+};
+/** Compression oracle (mirrors the future @browsercore/compression interface). */
+export const nodeZlib = {
+    gzip(data) {
+        return toBytes(gzipSync(data));
+    },
+    gunzip(data) {
+        return toBytes(gunzipSync(data));
+    },
+    deflate(data) {
+        return toBytes(deflateSync(data));
+    },
+    inflate(data) {
+        return toBytes(inflateSync(data));
+    },
+    brotliCompress(data) {
+        return toBytes(brotliCompressSync(data));
+    },
+    brotliDecompress(data) {
+        return toBytes(brotliDecompressSync(data));
+    },
+    /** The zlib window bits constant, for comparing deflate framing decisions. */
+    get zlibConstants() {
+        return zlibConstants;
+    },
+};
+/**
+ * Wire-format oracle for HTTP/1.1. Node's `http` module is the de-facto
+ * reference for the on-the-wire request/response format (RFC 7230). We use it
+ * to assert our serializer/parser produce bytes Node would accept and generate
+ * the same wire layout.
+ */
+export const nodeHttp = {
+    /**
+     * Build the request-line + headers block exactly as Node's http client would
+     * serialize them, so we can compare against our `serializeRequest`.
+     * Body is appended verbatim by the caller.
+     */
+    serializeRequestLineAndHeaders(method, url, headers) {
+        const lines = [`${method.toUpperCase()} ${url} HTTP/1.1`];
+        for (const [name, value] of headers) {
+            lines.push(`${name}: ${value}`);
+        }
+        // Node terminates the header section with a single blank line.
+        return new TextEncoder().encode(`${lines.join("\r\n")}\r\n\r\n`);
+    },
+};
+/** Narrow an unknown thrown value to an Error (mirrors transport.ensure*). */
+export function toError(e) {
+    if (e instanceof Error) {
+        return e;
+    }
+    return new Error(typeof e === "string" ? e : "unknown error");
+}
+/** Generic byte-level comparison returning a discriminated outcome. */
+export function compareBytesOutcome(a, b) {
+    if (bytesEqual(a, b)) {
+        return { equal: true };
+    }
+    return {
+        equal: false,
+        reason: `length ${a.length} vs ${b.length}${a.length === b.length ? `, first diff at byte ${firstDiff(a, b)}` : ""}`,
+    };
+}
+function firstDiff(a, b) {
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        if (a[i] !== b[i]) {
+            return i;
+        }
+    }
+    return len;
+}
+void assertNever;
+//# sourceMappingURL=node-reference.js.map

package/dist/reference/node-reference.js.map

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

package/dist/reference/reference.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Pluggable layered reference provider.
+ *
+ * The reference implementation is the source of truth for what a given browser
+ * profile SHOULD produce on the wire. Three backends are wrapped behind one
+ * facade:
+ *
+ * - `node-reference` (oracle) — Node's built-in crypto/dns/zlib/http
+ *   implementations, used as the spec oracle for primitive layers where Node IS
+ *   the reference (see `node-reference.ts`).
+ * - `curl-impersonate` (PRIMARY) — fast CI path; shells out to the
+ *   curl-impersonate binary to capture real traffic for a profile.
+ * - `real-browser` (SECONDARY) — loads pre-recorded captures from the
+ *   `captures/` directory, recorded from an actual browser.
+ *
+ * The {@link ReferenceProviderFacade} ties them together: capture resolves via
+ * primary then secondary; fingerprint is derived from the captured bytes; the
+ * node-reference oracle is exposed for primitive-layer comparisons.
+ *
+ * See docs/TEST-SUITE.md (Cat 3, 4, 14) for how references feed comparison.
+ */
+import type { ProfileId } from "@browsercore/profiles";
+import type { GoldenCapture } from "../types.js";
+import { TestingError } from "../errors.js";
+/** Which reference backend to use. Discriminated union — no bare string. */
+export type ReferenceProviderKind = {
+    readonly kind: "curl-impersonate";
+} | {
+    readonly kind: "real-browser";
+};
+/** Observable TLS/HTTP fingerprint of a captured reference exchange. */
+export interface Fingerprint {
+    readonly ja3: string;
+    readonly ja4: string;
+    readonly alpn: readonly string[];
+    readonly cipherSuite: string;
+    readonly protocolVersion: string;
+    readonly signatureAlgorithms: readonly string[];
+    readonly ellipticCurves: readonly string[];
+}
+/** Options for the curl-impersonate provider. */
+export interface CurlImpersonateOptions {
+    /** Path / name of the curl-impersonate binary. Default "curl-impersonate". */
+    readonly command: string;
+    /** Extra argv passed to the binary. */
+    readonly extraArgs?: readonly string[];
+}
+/** Options for the real-browser (pre-recorded capture) provider. */
+export interface RealBrowserOptions {
+    readonly command?: undefined;
+    /** Override captures directory. Defaults to the in-repo `captures/` dir. */
+    readonly capturesDir?: string;
+}
+/** Options for the {@link ReferenceProviderFacade}. */
+export interface ReferenceFacadeOptions {
+    readonly curl?: CurlImpersonateOptions;
+    readonly browser?: RealBrowserOptions;
+}
+/** A source of truth for a browser profile's wire behavior. */
+export interface ReferenceProvider {
+    readonly kind: ReferenceProviderKind;
+    capture(profile: ProfileId, url: string): Promise<GoldenCapture>;
+    fingerprint(profile: ProfileId): Promise<Fingerprint>;
+    availableProfiles(): ProfileId[];
+}
+/** Raised when a reference provider cannot capture or fingerprint a profile. */
+export declare class ReferenceError extends TestingError {
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * PRIMARY provider — shells out to curl-impersonate.
+ *
+ * `capture()` invokes the curl-impersonate binary against `url`, impersonating
+ * `profile`, and returns the raw bytes it observed on the wire. The binary
+ * must be on PATH (or in `command`); if it is missing, the call throws
+ * {@link ReferenceError} so the facade can fall back to the secondary.
+ */
+export declare class CurlImpersonateProvider implements ReferenceProvider {
+    readonly kind: ReferenceProviderKind;
+    readonly command: string;
+    readonly extraArgs: readonly string[];
+    constructor(options?: CurlImpersonateOptions);
+    availableProfiles(): ProfileId[];
+    capture(profile: ProfileId, url: string): Promise<GoldenCapture>;
+    fingerprint(profile: ProfileId): Promise<Fingerprint>;
+}
+/**
+ * SECONDARY provider — loads pre-recorded captures from the `captures/` dir.
+ *
+ * `capture()` resolves a stored capture for the profile; `fingerprint()`
+ * derives a {@link Fingerprint} from the captured bytes (only TLS
+ * ClientHellos are fingerprinted — other protocols return a stub).
+ */
+export declare class RealBrowserCaptureProvider implements ReferenceProvider {
+    readonly kind: ReferenceProviderKind;
+    readonly capturesDir: string;
+    constructor(options?: RealBrowserOptions);
+    availableProfiles(): ProfileId[];
+    capture(profile: ProfileId, _url: string): Promise<GoldenCapture>;
+    fingerprint(profile: ProfileId): Promise<Fingerprint>;
+}
+/**
+ * Facade wrapping the node-reference oracle + primary (curl-impersonate) and
+ * secondary (real-browser) providers behind a single {@link ReferenceProvider}.
+ *
+ * `capture()` tries the primary first; if it fails (binary missing, network
+ * error, ...) it falls back to the secondary's pre-recorded captures. The
+ * node-reference oracle is exposed via {@link ReferenceProviderFacade.nodeOracle}
+ * for primitive-layer comparisons (crypto, dns, zlib, wire format) — those
+ * layers are NOT fingerprinted here; they live in `node-reference.ts`.
+ */
+export declare class ReferenceProviderFacade implements ReferenceProvider {
+    readonly kind: ReferenceProviderKind;
+    private readonly primary;
+    private readonly secondary;
+    constructor(options?: ReferenceFacadeOptions);
+    /**
+     * Node-reference oracle — the spec oracle for primitive layers where Node
+     * IS the reference (crypto, dns, zlib, wire format). NOT used for
+     * browser-fingerprint comparison; that is what the providers are for.
+     */
+    get nodeOracle(): typeof nodeOracle;
+    availableProfiles(): ProfileId[];
+    capture(profile: ProfileId, url: string): Promise<GoldenCapture>;
+    fingerprint(profile: ProfileId): Promise<Fingerprint>;
+}
+/**
+ * Node-reference oracle re-export — the spec oracle for primitive layers.
+ *
+ * Imported lazily so the facade type references resolve without a cycle.
+ */
+import * as nodeOracle from "./node-reference.js";
+/** Construct the {@link ReferenceProvider} matching {@link ReferenceProviderKind}. */
+export declare function createReferenceProvider(kind: ReferenceProviderKind, options?: CurlImpersonateOptions | RealBrowserOptions): ReferenceProvider;
+/**
+ * Construct the full {@link ReferenceProviderFacade} wrapping both providers
+ * plus the node-reference oracle. This is the recommended entry point for
+ * tests that want primary→secondary fallback.
+ */
+export declare function createReferenceFacade(options?: ReferenceFacadeOptions): ReferenceProviderFacade;
+//# sourceMappingURL=reference.d.ts.map

package/dist/reference/reference.d.ts.map

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