@veryfront/ext-content-mdx 0.1.985

package/esm/src/errors/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Error categories for domain-based grouping and handling
+ */
+export type ErrorCategory = "CONFIG" | "BUILD" | "RUNTIME" | "ROUTE" | "MODULE" | "SERVER" | "BOUNDARY" | "DEV" | "DEPLOY" | "AGENT" | "GENERAL";
+/**
+ * RFC 9457 Problem Details response shape
+ */
+export interface RFC9457Response {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    category: ErrorCategory;
+    suggestion?: string;
+    cause?: string;
+}
+/**
+ * Error definition for the registry
+ */
+export interface ErrorDefinition {
+    slug: string;
+    category: ErrorCategory;
+    status: number;
+    title: string;
+    suggestion?: string;
+}
+/**
+ * Options for creating an error instance
+ */
+export interface ErrorCreateOptions {
+    /** Override the error message (defaults to detail or definition title) */
+    message?: string;
+    detail?: string;
+    cause?: unknown;
+    instance?: string;
+    context?: unknown;
+    /** Override the definition's default HTTP status (e.g., for per-request status codes) */
+    status?: number;
+}
+/**
+ * Registered error with factory method
+ */
+export interface RegisteredError extends ErrorDefinition {
+    create(options?: ErrorCreateOptions): VeryfrontError;
+}
+/**
+ * Define an error in the registry
+ */
+export declare function defineError(definition: ErrorDefinition): RegisteredError;
+/**
+ * Options for VeryfrontError constructor
+ */
+export interface VeryfrontErrorOptions extends ErrorCreateOptions {
+    slug: string;
+    category: ErrorCategory;
+    status: number;
+    title: string;
+    suggestion?: string;
+}
+/**
+ * Veryfront Error class with slug-based error identity
+ */
+export declare class VeryfrontError extends Error {
+    slug: string;
+    category: ErrorCategory;
+    status: number;
+    title: string;
+    suggestion?: string;
+    detail?: string;
+    cause?: unknown;
+    instance?: string;
+    context?: unknown;
+    constructor(message: string, options: VeryfrontErrorOptions);
+    /**
+     * Convert to RFC 9457 Problem Details format
+     */
+    toRFC9457(): RFC9457Response;
+    /**
+     * Get documentation URL for this error
+     */
+    getDocsUrl(): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/src/errors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/src/errors/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,OAAO,GACP,SAAS,GACT,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,KAAK,GACL,QAAQ,GACR,OAAO,GACP,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,MAAM,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAAC;CACtD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,eAAe,GAAG,eAAe,CAiBxE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IACP,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEN,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB;IAe3D;;OAEG;IACH,SAAS,IAAI,eAAe;IAa5B;;OAEG;IACH,UAAU,IAAI,MAAM;CAGrB"}

package/esm/src/errors/types.js

@@ -0,0 +1,69 @@
+/**
+ * Define an error in the registry
+ */
+export function defineError(definition) {
+    return {
+        ...definition,
+        create(options) {
+            return new VeryfrontError(options?.message || options?.detail || definition.title, {
+                slug: definition.slug,
+                category: definition.category,
+                status: options?.status ?? definition.status,
+                title: definition.title,
+                suggestion: definition.suggestion,
+                detail: options?.detail,
+                cause: options?.cause,
+                instance: options?.instance,
+                context: options?.context,
+            });
+        },
+    };
+}
+/**
+ * Veryfront Error class with slug-based error identity
+ */
+export class VeryfrontError extends Error {
+    slug;
+    category;
+    status;
+    title;
+    suggestion;
+    detail;
+    cause;
+    instance;
+    context;
+    constructor(message, options) {
+        super(message);
+        this.name = "VeryfrontError";
+        this.slug = options.slug;
+        this.category = options.category;
+        this.status = options.status;
+        this.title = options.title;
+        this.suggestion = options.suggestion;
+        this.detail = options.detail;
+        this.cause = options.cause;
+        this.instance = options.instance;
+        this.context = options.context;
+    }
+    /**
+     * Convert to RFC 9457 Problem Details format
+     */
+    toRFC9457() {
+        return {
+            type: `https://veryfront.com/docs/errors/${this.slug}`,
+            title: this.title,
+            status: this.status,
+            detail: this.detail,
+            instance: this.instance,
+            category: this.category,
+            suggestion: this.suggestion,
+            cause: typeof this.cause === "string" ? this.cause : undefined,
+        };
+    }
+    /**
+     * Get documentation URL for this error
+     */
+    getDocsUrl() {
+        return `https://veryfront.com/docs/errors/${this.slug}`;
+    }
+}

package/esm/src/errors/veryfront-error.d.ts

@@ -0,0 +1,149 @@
+export interface BuildContext {
+    file?: string;
+    line?: number;
+    column?: number;
+    moduleId?: string;
+    phase?: "parse" | "transform" | "bundle" | "optimize" | "dependency-resolution" | "circuit-breaker" | "http-bundle-validation";
+    /** Number of failures (for circuit breaker) */
+    failures?: number;
+    /** Missing dependencies list */
+    missing?: Array<{
+        specifier: string;
+        fromFile: string;
+        reason: string;
+    }>;
+    /** Failed HTTP bundle specifiers */
+    failed?: string[];
+    /** Cache directory path */
+    cacheDir?: string;
+}
+export interface APIContext {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    headers?: Record<string, string>;
+}
+export interface RenderContext {
+    component?: string;
+    route?: string;
+    phase?: "server" | "client" | "hydration";
+    props?: unknown;
+}
+export interface ConfigContext {
+    configFile?: string;
+    field?: string;
+    value?: unknown;
+    expected?: string;
+}
+export interface AgentContext {
+    agentId?: string;
+    intent?: string;
+    timeout?: number;
+}
+export interface FileContext {
+    path?: string;
+    operation?: "read" | "write" | "delete" | "mkdir";
+    permissions?: string;
+}
+interface NetworkContext {
+    url?: string;
+    timeout?: number;
+    retryCount?: number;
+}
+/**
+ * Discriminated union for serializable error data.
+ *
+ * This represents error DATA (plain objects), not throwable errors.
+ * For throwable errors, use `VeryfrontError` class from `./types.ts`.
+ */
+export type VeryfrontErrorData = {
+    type: "build";
+    message: string;
+    context?: BuildContext;
+} | {
+    type: "api";
+    message: string;
+    context?: APIContext;
+} | {
+    type: "render";
+    message: string;
+    context?: RenderContext;
+} | {
+    type: "config";
+    message: string;
+    context?: ConfigContext;
+} | {
+    type: "agent";
+    message: string;
+    context?: AgentContext;
+} | {
+    type: "file";
+    message: string;
+    context?: FileContext;
+} | {
+    type: "network";
+    message: string;
+    context?: NetworkContext;
+} | {
+    type: "permission";
+    message: string;
+    context?: FileContext;
+} | {
+    type: "not_supported";
+    message: string;
+    feature?: string;
+} | {
+    type: "no_ai_available";
+    message: string;
+};
+export declare function createError(error: VeryfrontErrorData): VeryfrontErrorData;
+export declare const isBuildError: (error: VeryfrontErrorData) => error is {
+    type: "build";
+    message: string;
+    context?: BuildContext;
+};
+export declare const isAPIError: (error: VeryfrontErrorData) => error is {
+    type: "api";
+    message: string;
+    context?: APIContext;
+};
+export declare const isRenderError: (error: VeryfrontErrorData) => error is {
+    type: "render";
+    message: string;
+    context?: RenderContext;
+};
+export declare const isConfigError: (error: VeryfrontErrorData) => error is {
+    type: "config";
+    message: string;
+    context?: ConfigContext;
+};
+export declare const isFileError: (error: VeryfrontErrorData) => error is {
+    type: "file";
+    message: string;
+    context?: FileContext;
+};
+export declare const isNetworkError: (error: VeryfrontErrorData) => error is {
+    type: "network";
+    message: string;
+    context?: NetworkContext;
+};
+/**
+ * Convert a VeryfrontErrorData (plain object) to a throwable Error instance.
+ *
+ * Uses Error.captureStackTrace when available (V8 engines) to exclude toError()
+ * from the stack trace, making the stack point to the actual call site.
+ *
+ * @see plans/architecture-audit/010.3-dual-veryfront-error-definitions.md
+ */
+export declare function toError(veryfrontError: VeryfrontErrorData): Error;
+export declare function fromError(error: unknown): VeryfrontErrorData | null;
+/**
+ * Extract error message from any error type
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Ensure error is an Error instance
+ */
+export declare function ensureError(error: unknown): Error;
+export {};
+//# sourceMappingURL=veryfront-error.d.ts.map

package/esm/src/errors/veryfront-error.d.ts.map

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

package/esm/src/errors/veryfront-error.js

@@ -0,0 +1,61 @@
+export function createError(error) {
+    return error;
+}
+/** Type guard factory for VeryfrontErrorData types */
+function isErrorType(type) {
+    return (error) => error.type === type;
+}
+export const isBuildError = isErrorType("build");
+export const isAPIError = isErrorType("api");
+export const isRenderError = isErrorType("render");
+export const isConfigError = isErrorType("config");
+export const isFileError = isErrorType("file");
+export const isNetworkError = isErrorType("network");
+/**
+ * Convert a VeryfrontErrorData (plain object) to a throwable Error instance.
+ *
+ * Uses Error.captureStackTrace when available (V8 engines) to exclude toError()
+ * from the stack trace, making the stack point to the actual call site.
+ *
+ * @see plans/architecture-audit/010.3-dual-veryfront-error-definitions.md
+ */
+export function toError(veryfrontError) {
+    const error = new Error(veryfrontError.message);
+    error.name = `VeryfrontError[${veryfrontError.type}]`;
+    // Capture stack at call site, excluding toError from the trace
+    // This makes debugging easier by showing where createError+toError was called
+    if (Error.captureStackTrace)
+        Error.captureStackTrace(error, toError);
+    Object.defineProperty(error, "context", {
+        value: veryfrontError,
+        enumerable: false,
+        configurable: true,
+    });
+    return error;
+}
+export function fromError(error) {
+    if (!error || typeof error !== "object" || !("context" in error))
+        return null;
+    const context = error.context;
+    if (!context || typeof context !== "object")
+        return null;
+    if (!("type" in context) || !("message" in context))
+        return null;
+    return context;
+}
+/**
+ * Extract error message from any error type
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/**
+ * Ensure error is an Error instance
+ */
+export function ensureError(error) {
+    if (error instanceof Error)
+        return error;
+    return new Error(String(error));
+}

package/esm/src/modules/react-loader/ssr-module-loader/concurrency/semaphore.d.ts

@@ -0,0 +1,13 @@
+export declare class Semaphore {
+    private permits;
+    private readonly maxQueueSize;
+    private waitQueue;
+    constructor(permits: number, options?: {
+        maxQueueSize?: number;
+    });
+    tryAcquire(timeoutMs?: number): Promise<boolean>;
+    release(): void;
+    get available(): number;
+    get waiting(): number;
+}
+//# sourceMappingURL=semaphore.d.ts.map

package/esm/src/modules/react-loader/ssr-module-loader/concurrency/semaphore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.d.ts","sourceRoot":"","sources":["../../../../../../src/src/modules/react-loader/ssr-module-loader/concurrency/semaphore.ts"],"names":[],"mappings":"AAKA,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,SAAS,CAAoE;gBAEzE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAKhE,UAAU,CAAC,SAAS,SAA6B,GAAG,OAAO,CAAC,OAAO,CAAC;IAkCpE,OAAO,IAAI,IAAI;IAUf,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF"}

package/esm/src/modules/react-loader/ssr-module-loader/concurrency/semaphore.js

@@ -0,0 +1,55 @@
+/** Default timeout for acquiring a semaphore permit (ms) */
+import * as dntShim from "../../../../../_dnt.shims.js";
+const DEFAULT_ACQUIRE_TIMEOUT_MS = 100;
+export class Semaphore {
+    permits;
+    maxQueueSize;
+    waitQueue = [];
+    constructor(permits, options) {
+        this.permits = permits;
+        this.maxQueueSize = options?.maxQueueSize ?? Infinity;
+    }
+    tryAcquire(timeoutMs = DEFAULT_ACQUIRE_TIMEOUT_MS) {
+        if (this.permits > 0) {
+            this.permits--;
+            return Promise.resolve(true);
+        }
+        if (this.waitQueue.length >= this.maxQueueSize) {
+            return Promise.resolve(false);
+        }
+        return new Promise((resolve) => {
+            let settled = false;
+            const onAcquire = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutId);
+                resolve(true);
+            };
+            const timeoutId = dntShim.setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                const index = this.waitQueue.findIndex((w) => w.resolve === onAcquire);
+                if (index !== -1)
+                    this.waitQueue.splice(index, 1);
+                resolve(false);
+            }, timeoutMs);
+            this.waitQueue.push({ resolve: onAcquire, reject: onAcquire });
+        });
+    }
+    release() {
+        const next = this.waitQueue.shift();
+        if (next) {
+            next.resolve();
+            return;
+        }
+        this.permits++;
+    }
+    get available() {
+        return this.permits;
+    }
+    get waiting() {
+        return this.waitQueue.length;
+    }
+}

package/esm/src/observability/tracing/api-shim.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Thin in-process shim for `@opentelemetry/api`.
+ *
+ * Core files that previously imported directly from `@opentelemetry/api` now
+ * import from this module.  When the `ext-observability-opentelemetry` extension is present
+ * the real SDK provider is wired in via `setGlobalTracerProvider`; otherwise
+ * every call falls back to a no-op implementation so the core boots without the
+ * extension installed.
+ *
+ * **Tracing types and constants** (exported for call-site use):
+ *   `Span`, `Tracer`, `TracerProvider`, `Context`, `TextMapPropagator`
+ *   `SpanKind`, `SpanStatusCode`
+ *
+ * **Metrics types** (re-exported structural shapes for the metrics subsystem;
+ * not backed by a live SDK — the metrics subsystem is wired separately):
+ *   `Meter`, `Counter`, `Histogram`, `ObservableGauge`, `UpDownCounter`,
+ *   `ObservableResult`
+ *
+ * @module observability/tracing/api-shim
+ */
+export type AttributeValue = string | number | boolean | undefined;
+export interface Span {
+    setAttribute(key: string, value: AttributeValue): Span;
+    setAttributes(attrs: Record<string, AttributeValue>): Span;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): Span;
+    recordException(err: unknown): void;
+    addEvent(name: string, attrs?: Record<string, AttributeValue>): Span;
+    end(endTime?: number): void;
+    spanContext(): SpanContext;
+    updateName(name: string): void;
+}
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+export interface Tracer {
+    startSpan(name: string, options?: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+    }, context?: Context): Span;
+    startActiveSpan<T>(name: string, fn: (span: Span) => T): T;
+    startActiveSpan<T>(name: string, options: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+    }, fn: (span: Span) => T): T;
+    startActiveSpan<T>(name: string, options: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+    }, context: Context, fn: (span: Span) => T): T;
+}
+export interface TracerProvider {
+    getTracer(name: string, version?: string): Tracer;
+}
+export interface Context {
+    getValue(key: symbol): unknown;
+    setValue(key: symbol, value: unknown): Context;
+    deleteValue(key: symbol): Context;
+}
+export interface TextMapGetter<C = Record<string, string>> {
+    keys(carrier: C): string[];
+    get(carrier: C, key: string): string | string[] | undefined;
+}
+export interface TextMapSetter<C = Record<string, string>> {
+    set(carrier: C, key: string, value: string): void;
+}
+export interface TextMapPropagator {
+    inject(context: Context, carrier: unknown, setter?: TextMapSetter<unknown>): void;
+    extract(context: Context, carrier: unknown, getter?: TextMapGetter<unknown>): Context;
+    fields(): string[];
+}
+export declare const SpanKind: {
+    readonly INTERNAL: 0;
+    readonly SERVER: 1;
+    readonly CLIENT: 2;
+    readonly PRODUCER: 3;
+    readonly CONSUMER: 4;
+};
+export type SpanKind = typeof SpanKind[keyof typeof SpanKind];
+export declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+export type SpanStatusCode = typeof SpanStatusCode[keyof typeof SpanStatusCode];
+export interface ObservableResult {
+    observe(value: number, attributes?: Record<string, AttributeValue>): void;
+}
+export interface Counter {
+    add(value: number, attributes?: Record<string, AttributeValue>): void;
+}
+export interface UpDownCounter {
+    add(value: number, attributes?: Record<string, AttributeValue>): void;
+}
+export interface Histogram {
+    record(value: number, attributes?: Record<string, AttributeValue>): void;
+}
+export interface ObservableGauge {
+    addCallback(callback: (result: ObservableResult) => void): void;
+}
+export interface Meter {
+    createCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): Counter;
+    createUpDownCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): UpDownCounter;
+    createHistogram(name: string, options?: {
+        description?: string;
+        unit?: string;
+        advice?: {
+            explicitBucketBoundaries?: number[];
+        };
+    }): Histogram;
+    createObservableGauge(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): ObservableGauge;
+    getMeter?: never;
+}
+export interface MetricsAPI {
+    getMeter(name: string | undefined, version?: string): Meter;
+}
+/**
+ * Register the real OTel trace API's span accessors. Called by the
+ * ext-observability-opentelemetry extension after it wires the SDK so that the shim's
+ * `trace.getActiveSpan()` / `trace.getSpan()` can return real spans.
+ */
+export declare function setGlobalActiveSpanAccessor(accessor: {
+    getActiveSpan(): Span | undefined;
+    getSpan(ctx: Context): Span | undefined;
+}): void;
+/**
+ * Wire in the real SDK TracerProvider.
+ * Called from `src/server/bootstrap.ts` after `orchestrateExtensions()` runs.
+ */
+export declare function setGlobalTracerProvider(p: TracerProvider): void;
+export declare function getGlobalTracerProvider(): TracerProvider;
+export declare function getTracerProviderRevision(): number;
+/**
+ * Get a tracer from the active provider.
+ * Returns the no-op tracer when ext-observability-opentelemetry is not installed.
+ */
+export declare function getTracer(name: string, version?: string): Tracer;
+export declare const context: {
+    active(): Context;
+    with<T>(ctx: Context, fn: () => T): T;
+    setGlobalContextManager(_mgr: unknown): void;
+};
+export declare const trace: {
+    getTracer(name: string, version?: string): Tracer;
+    setGlobalTracerProvider(p: TracerProvider): void;
+    getGlobalTracerProvider(): TracerProvider;
+    setSpan(ctx: Context, _span: Span): Context;
+    getSpan(ctx: Context): Span | undefined;
+    getActiveSpan(): Span | undefined;
+};
+export declare const propagation: {
+    setGlobalPropagator(p: TextMapPropagator): void;
+    extract<C>(ctx: Context, carrier: C, getter?: TextMapGetter<C>): Context;
+    inject<C>(ctx: Context, carrier: C, setter?: TextMapSetter<C>): void;
+};
+export declare const defaultTextMapGetter: TextMapGetter<Record<string, string>>;
+export declare const defaultTextMapSetter: TextMapSetter<Record<string, string>>;
+/**
+ * Register the OTel Metrics API (from the SDK).
+ * Called by ext-observability-opentelemetry in its setup hook so the metrics subsystem
+ * can use `getMeter()` when available.
+ */
+export declare function setGlobalMetricsAPI(api: MetricsAPI): void;
+export declare function getGlobalMetricsAPI(): MetricsAPI | null;
+export declare function _resetShimForTests(): void;
+//# sourceMappingURL=api-shim.d.ts.map

package/esm/src/observability/tracing/api-shim.d.ts.map

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