@oxy.so/telemetry 2.1.0 → 2.2.0

package/dist/esm/server.js

@@ -1,4 +1,6 @@
+import { OXY_ACTIVITY_ID_HEADER, OXY_EDGE_REGION_HEADER, } from './index.js';
 export const DEFAULT_PRESENCE_BUCKET_MS = 30000;
+/** @deprecated Unused by any Oxy repo; `presenceKeys` already encodes the window. Removal is planned for the next major. */
 export const DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60000;
 function firstHeaderValue(value) {
     if (typeof value === 'string')
@@ -15,23 +17,43 @@ export function normalizeActivityId(value) {
     const candidate = firstHeaderValue(value);
     return candidate && /^[a-z0-9_-]{16,64}$/i.test(candidate) ? candidate : undefined;
 }
+/**
+ * The collector's source region for a normalised edge PoP (`edge-<pop>`), the
+ * one derivation every reporter shares. `undefined` when there is no PoP.
+ */
+export function sourceRegionFromEdgePop(edgePop) {
+    return edgePop ? `edge-${edgePop}` : undefined;
+}
 export function metadataFromHeaders(headers) {
-    const forwardedPop = normalizeEdgePop(headers['x-oxy-edge-region']);
+    const forwardedPop = normalizeEdgePop(headers[OXY_EDGE_REGION_HEADER.toLowerCase()]);
     const ray = firstHeaderValue(headers['cf-ray']);
     const rayPop = ray?.match(/-([a-z]{3})$/i)?.[1]?.toLowerCase();
-    const activityId = normalizeActivityId(headers['x-oxy-activity-id']);
+    const activityId = normalizeActivityId(headers[OXY_ACTIVITY_ID_HEADER.toLowerCase()]);
     return {
         ...(activityId ? { activityId } : {}),
         ...(forwardedPop || rayPop ? { edgePop: forwardedPop ?? rayPop } : {}),
     };
 }
+/**
+ * @deprecated Unused by any Oxy repo. For the bounded activity category of a
+ * path use `trafficType` from `@oxy.so/telemetry/collector`. Removal is planned
+ * for the next major.
+ */
 export function serviceFromPath(path) {
     const segment = path.split('/').filter(Boolean)[0];
     return segment && /^[a-z][a-z0-9-]{0,31}$/i.test(segment) ? segment.toLowerCase() : 'platform';
 }
+/**
+ * @deprecated Unused by any Oxy repo; `createTrafficCollector` keys its own
+ * flows. Removal is planned for the next major.
+ */
 export function activityFlow(sourceRegion, service) {
     return { sourceRegion, service, key: `${sourceRegion ?? ''}|${service}` };
 }
+/**
+ * @deprecated Unused outside `presenceKeys`; call `presenceKeys` for the
+ * current and previous bucket keys. Removal is planned for the next major.
+ */
 export function presenceBucket(observedAt, bucketMs = DEFAULT_PRESENCE_BUCKET_MS) {
     if (!Number.isFinite(observedAt) || !Number.isFinite(bucketMs) || bucketMs <= 0) {
         throw new RangeError('observedAt and bucketMs must define a finite positive bucket');

package/dist/esm/socket.js

@@ -1,5 +1,5 @@
 import { normalizeInfrastructureRegion } from './collector.js';
-import { metadataFromHeaders } from './server.js';
+import { metadataFromHeaders, sourceRegionFromEdgePop } from './server.js';
 const CATEGORIES = {
     auth: 'identity',
     session: 'identity',
@@ -44,9 +44,7 @@ export function observeTrafficSocket(socket, collector, service, region, options
         const edgePop = metadataFromHeaders(socket.handshake.headers).edgePop;
         const peerRegion = peerService
             ? normalizeInfrastructureRegion(peer?.region)
-            : edgePop
-                ? `edge-${edgePop}`
-                : undefined;
+            : sourceRegionFromEdgePop(edgePop);
         collector.record({
             region,
             service,
@@ -85,9 +83,7 @@ export function observeTrafficWebSocket(socket, collector, service, region, opti
         const edgePop = metadataFromHeaders(options.headers ?? {}).edgePop;
         const peerRegion = peerService
             ? normalizeInfrastructureRegion(peer?.region)
-            : edgePop
-                ? `edge-${edgePop}`
-                : undefined;
+            : sourceRegionFromEdgePop(edgePop);
         collector.record({
             service,
             region,

package/dist/types/browser.d.ts

@@ -32,9 +32,20 @@ export interface BrowserTelemetry {
     peekEdgeRegionHeader(): Record<string, string>;
     getHeaders(): Promise<Record<string, string>>;
 }
+/**
+ * @deprecated No Oxy repo constructs its own runtime: use the module-level
+ * `getBrowserActivityIdHeader`, `getBrowserEdgeRegionHeader` and
+ * `peekBrowserEdgeRegionHeader`. The factory remains the test seam. Removal from
+ * the public surface is planned for the next major.
+ */
 export declare function createBrowserTelemetry(options?: BrowserTelemetryOptions): BrowserTelemetry;
 export declare const getBrowserActivityIdHeader: () => Record<string, string>;
 export declare const getBrowserEdgeRegionHeader: () => Promise<Record<string, string>>;
 export declare const peekBrowserEdgeRegionHeader: () => Record<string, string>;
+/**
+ * @deprecated Unused by any Oxy repo. `@oxy.so/core` sends
+ * `peekBrowserEdgeRegionHeader()` and `getBrowserActivityIdHeader()` per request.
+ * Removal is planned for the next major.
+ */
 export declare const getBrowserTelemetryHeaders: () => Promise<Record<string, string>>;
 export {};

package/dist/types/collector.d.ts

@@ -1,24 +1,26 @@
+import { type TrafficAggregate, type TrafficFlow, type TrafficType } from './index.js';
 import { type TelemetryHeaders } from './server.js';
-export type TrafficScope = 'internal' | 'external';
-export type TrafficDirection = 'inbound' | 'outbound';
-export type TrafficType = 'identity' | 'ai' | 'communication' | 'media' | 'platform';
-export interface TrafficFlow {
-    region: string;
-    sourceRegion?: string;
-    targetRegion?: string;
-    sourceService?: string;
-    targetService?: string;
-    service: string;
-    scope: TrafficScope;
-    direction: TrafficDirection;
-    activityType: TrafficType;
-}
-export interface TrafficAggregate extends TrafficFlow {
-    requests: number;
-    windowStartedAt: string;
-    emittedAt: string;
-}
+export type { TrafficAggregate, TrafficDirection, TrafficFlow, TrafficScope, TrafficType, } from './index.js';
 export declare function trafficType(path: string): TrafficType;
+/** Which side of a request a reporter is observing. */
+export type ObservationDirection = 'inbound' | 'outbound';
+/**
+ * Every path a reporter does not observe, in ONE table. Each entry says which
+ * directions it applies to: the inbound and outbound sets differ today (an
+ * outbound call to a probe or to `/platform-stats` IS recorded), and that is
+ * preserved exactly. Unifying them is a separate, deliberate decision.
+ */
+export declare const UNOBSERVED_PATHS: readonly {
+    readonly directions: ObservationDirection | 'both';
+    readonly matches: (path: string) => boolean;
+}[];
+/**
+ * Is this path part of what a reporter observes in this direction? Collection
+ * itself, service-token minting and (inbound) probes and the dashboard
+ * transport are control traffic: observing them would feed back into the very
+ * activity they carry.
+ */
+export declare function isObservedPath(path: string, direction: ObservationDirection): boolean;
 export declare function createTrafficCollector(publish: (events: TrafficAggregate[]) => Promise<unknown>, now?: () => number): {
     record(flow: TrafficFlow): void;
     flush(): Promise<void>;
@@ -47,4 +49,3 @@ export declare function infrastructureLocation(region: string): {
     coordinates: [number, number];
 };
 export declare function normalizeInfrastructureRegion(value: unknown): string | undefined;
-export {};

package/dist/types/index.d.ts

@@ -1,16 +1,69 @@
+/** Request header a browser sends: the ephemeral anonymous activity ID. */
 export declare const OXY_ACTIVITY_ID_HEADER = "X-Oxy-Activity-Id";
+/** Request header a browser sends: the three-letter Cloudflare PoP code. */
 export declare const OXY_EDGE_REGION_HEADER = "X-Oxy-Edge-Region";
+/** Response header a reporting service sets: the region that processed the request. */
+export declare const OXY_REGION_HEADER = "X-Oxy-Region";
+/** Request header one Oxy service sends another: the caller's infrastructure region. */
+export declare const OXY_SOURCE_REGION_HEADER = "X-Oxy-Source-Region";
+/**
+ * Request headers a browser may send and a CORS allow-list must therefore
+ * permit (`Access-Control-Allow-Headers`). `X-Oxy-Source-Region` is service to
+ * service only and is deliberately absent. The list is derived from the
+ * constants above, so a CORS list built from it cannot drift from them.
+ */
+export declare const OXY_TELEMETRY_REQUEST_HEADERS: readonly string[];
+/**
+ * Response headers a browser client may need to read
+ * (`Access-Control-Expose-Headers`).
+ */
+export declare const OXY_TELEMETRY_EXPOSED_HEADERS: readonly string[];
 export interface AnonymousActivityMetadata {
     activityId?: string;
     edgePop?: string;
 }
-export interface ActivityAggregate {
+export type TrafficScope = 'internal' | 'external';
+export type TrafficDirection = 'inbound' | 'outbound';
+export type TrafficType = 'identity' | 'ai' | 'communication' | 'media' | 'platform';
+/** One observed flow, as a reporter records it. */
+export interface TrafficFlow {
+    region: string;
     sourceRegion?: string;
-    targetRegion: string;
+    targetRegion?: string;
+    sourceService?: string;
+    targetService?: string;
     service: string;
+    scope: TrafficScope;
+    direction: TrafficDirection;
+    activityType: TrafficType;
+}
+/**
+ * A flow with its request count and window: the exact shape the API's strict
+ * `platformActivityBatchSchema` accepts on `POST /internal/activity`.
+ */
+export interface TrafficAggregate extends TrafficFlow {
     requests: number;
-    activeClients: number;
     windowStartedAt: string;
     emittedAt: string;
-    direction: 'inbound';
+}
+/**
+ * The `platform_activity` socket payload: an aggregate plus the approximate
+ * active-client count for its origin.
+ */
+export type ActivityAggregate = TrafficAggregate & {
+    activeClients: number;
+};
+/** One region in the `platform_infrastructure` snapshot. */
+export interface InfrastructureNode {
+    region: string;
+    label: string;
+    coordinates: [number, number];
+    services: string[];
+    instances: number;
+    status: 'online' | 'degraded' | 'offline' | 'unknown';
+}
+/** The `platform_infrastructure` socket payload. */
+export interface InfrastructureSnapshot {
+    emittedAt: string;
+    nodes: InfrastructureNode[];
 }

package/dist/types/metrics.d.ts

@@ -76,4 +76,9 @@ export declare const HTTP_REQUEST_LATENCY: MetricDefinition;
 export declare const HTTP_RATE_LIMITED: MetricDefinition;
 /** `2xx`, `4xx`, … — a closed set, safe as a dimension. */
 export declare function statusClass(status: number): string;
+/**
+ * `createEmfPublisher` on ECS, `null` everywhere else (a laptop, CI, a test):
+ * the gate oxy-api and Mention each repeated. `env` is injectable for tests.
+ */
+export declare function createEmfPublisherIfDeployed(options: EmfPublisherOptions, env?: Readonly<Record<string, string | undefined>>): EmfPublisher | null;
 export declare function createEmfPublisher(options: EmfPublisherOptions): EmfPublisher;

package/dist/types/server.d.ts

@@ -1,12 +1,18 @@
-import type { ActivityAggregate, AnonymousActivityMetadata } from './index.js';
+import { type ActivityAggregate, type AnonymousActivityMetadata } from './index.js';
 export declare const DEFAULT_PRESENCE_BUCKET_MS = 30000;
+/** @deprecated Unused by any Oxy repo; `presenceKeys` already encodes the window. Removal is planned for the next major. */
 export declare const DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60000;
 export type TelemetryHeaderValue = string | readonly string[] | undefined;
 export type TelemetryHeaders = Readonly<Record<string, TelemetryHeaderValue>>;
+/**
+ * @deprecated Unused by any Oxy repo (presence counting lives in the API). No
+ * replacement; removal is planned for the next major.
+ */
 export interface ActivityCardinalityAdapter {
     add(key: string, activityId: string, ttlSeconds: number): Promise<void>;
     count(keys: readonly string[]): Promise<number>;
 }
+/** @deprecated Unused by any Oxy repo; see `activityFlow`. */
 export interface ActivityFlow {
     sourceRegion?: string;
     service: string;
@@ -14,9 +20,28 @@ export interface ActivityFlow {
 }
 export declare function normalizeEdgePop(value: TelemetryHeaderValue): string | undefined;
 export declare function normalizeActivityId(value: TelemetryHeaderValue): string | undefined;
+/**
+ * The collector's source region for a normalised edge PoP (`edge-<pop>`), the
+ * one derivation every reporter shares. `undefined` when there is no PoP.
+ */
+export declare function sourceRegionFromEdgePop(edgePop: string | undefined): string | undefined;
 export declare function metadataFromHeaders(headers: TelemetryHeaders): AnonymousActivityMetadata;
+/**
+ * @deprecated Unused by any Oxy repo. For the bounded activity category of a
+ * path use `trafficType` from `@oxy.so/telemetry/collector`. Removal is planned
+ * for the next major.
+ */
 export declare function serviceFromPath(path: string): string;
+/**
+ * @deprecated Unused by any Oxy repo; `createTrafficCollector` keys its own
+ * flows. Removal is planned for the next major.
+ */
 export declare function activityFlow(sourceRegion: string | undefined, service: string): ActivityFlow;
+/**
+ * @deprecated Unused outside `presenceKeys`; call `presenceKeys` for the
+ * current and previous bucket keys. Removal is planned for the next major.
+ */
 export declare function presenceBucket(observedAt: number, bucketMs?: number): number;
 export declare function presenceKeys(sourceRegion: string, observedAt: number, bucketMs?: number): readonly [string, string];
+/** @deprecated Unused by any Oxy repo; use `ActivityAggregate` from `@oxy.so/telemetry`. */
 export type ActivityBucket = ActivityAggregate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/telemetry",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Framework-agnostic anonymous activity telemetry and CloudWatch EMF metrics primitives for Oxy services.",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -105,8 +105,10 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!dist/.oxy-source-digest"
   ],
+  "oxySourceStamp": "dist",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OxyHQ/oxy.git",
@@ -119,23 +121,22 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "bun run clean && bun run build:cjs && bun run build:esm && bun run build:types",
+    "build": "bun run clean && bun run build:cjs && bun run build:esm && bun run build:types && node -e \"const p='../app-preset/metro/source-stamp.js';require('node:fs').existsSync(p)&&require(p).writeStamp(process.cwd())\"",
     "build:cjs": "tsc -p tsconfig.cjs.json && node scripts/mark-cjs.mjs",
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:types": "tsc -p tsconfig.types.json && node scripts/mark-types-cjs.mjs",
     "clean": "rm -rf dist",
     "typescript": "tsc --noEmit",
     "test": "jest",
-    "lint": "biome lint --error-on-warnings ./src",
-    "prepublishOnly": "node ../../scripts/assert-bun-publish.mjs && bun run typescript && bun run test && bun run build"
+    "lint": "biome lint --error-on-warnings ./src"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "jest": "^30.5.1",
-    "jest-environment-jsdom": "^30.5.1",
-    "socket.io": "^4.8.1",
-    "socket.io-client": "^4.8.1",
-    "ts-jest": "^29.4.12",
-    "typescript": "^5.9.2"
+    "jest": "^30.5.2",
+    "jest-environment-jsdom": "^30.5.2",
+    "socket.io": "^4.8.4",
+    "socket.io-client": "^4.8.4",
+    "ts-jest": "^29.4.15",
+    "typescript": "~6.0.3"
   }
 }

package/src/__tests__/collector.test.ts

@@ -3,6 +3,7 @@ import { EventEmitter } from 'node:events';
 import {
   createTrafficCollector,
   instrumentTrafficFetch,
+  resolveOxyServiceEndpoint,
   trafficMiddleware,
   trafficType,
   type TrafficAggregate,
@@ -197,4 +198,20 @@ describe('ecosystem activity collector', () => {
     expect(trafficType('/api/v1/uploads/private-id?token=secret')).toBe('media');
     expect(trafficType('/v1/chat/completions')).toBe('ai');
   });
+
+  it('attributes the Gemies API to gemies and keeps Alia’s API as alia', () => {
+    expect(resolveOxyServiceEndpoint(new URL('https://api.gemies.ai/v1/chat'))).toEqual({
+      service: 'gemies',
+      region: 'us-west-2',
+    });
+    expect(resolveOxyServiceEndpoint(new URL('https://api.alia.onl/v1/chat'))?.service).toBe(
+      'alia',
+    );
+    // Exact host only: neither the web app nor a lookalike claims the service.
+    expect(resolveOxyServiceEndpoint(new URL('https://gemies.ai/'))).toBeUndefined();
+    expect(
+      resolveOxyServiceEndpoint(new URL('https://api.gemies.ai.evil.example/')),
+    ).toBeUndefined();
+    expect(resolveOxyServiceEndpoint(new URL('http://api.gemies.ai/'))).toBeUndefined();
+  });
 });

package/src/__tests__/emfGolden.test.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createEmfPublisher, type MetricDefinition } from '../metrics';
+
+// The cross-language contract: Kaana's Go `internal/emf` runs the same file.
+// Numbers JSON cannot carry travel as the strings below.
+const SENTINELS: Record<string, number> = {
+  NaN: Number.NaN,
+  Infinity: Number.POSITIVE_INFINITY,
+  '-Infinity': Number.NEGATIVE_INFINITY,
+};
+
+interface GoldenCase {
+  name: string;
+  definition: MetricDefinition;
+  service: string;
+  namespace: string;
+  now: number;
+  maxSeries?: number;
+  observations: { labels: Record<string, string>; value: number | string }[];
+  expectedLines: unknown[];
+}
+
+const cases: GoldenCase[] = JSON.parse(
+  readFileSync(join(__dirname, '..', '..', 'fixtures', 'emf-golden.json'), 'utf8'),
+);
+
+describe('EMF golden fixture', () => {
+  it('is not empty and has unique case names', () => {
+    expect(cases.length).toBeGreaterThan(0);
+    expect(new Set(cases.map((entry) => entry.name)).size).toBe(cases.length);
+  });
+
+  it.each(cases.map((entry) => [entry.name, entry] as const))('%s', (_name, entry) => {
+    const lines: string[] = [];
+    const publisher = createEmfPublisher({
+      namespace: entry.namespace,
+      service: entry.service,
+      write: (line) => lines.push(line),
+      now: () => entry.now,
+      ...(entry.maxSeries === undefined ? {} : { maxSeries: entry.maxSeries }),
+    });
+    for (const { labels, value } of entry.observations) {
+      publisher.record(
+        entry.definition,
+        typeof value === 'string' ? SENTINELS[value] : value,
+        labels,
+      );
+    }
+    publisher.stop();
+    expect(lines.map((line) => JSON.parse(line))).toEqual(entry.expectedLines);
+  });
+});

package/src/__tests__/singleSources.test.ts

@@ -0,0 +1,184 @@
+/** @jest-environment node */
+import { isObservedPath } from '../collector';
+import {
+  OXY_ACTIVITY_ID_HEADER,
+  OXY_EDGE_REGION_HEADER,
+  OXY_REGION_HEADER,
+  OXY_SOURCE_REGION_HEADER,
+  OXY_TELEMETRY_EXPOSED_HEADERS,
+  OXY_TELEMETRY_REQUEST_HEADERS,
+} from '../index';
+import { createEmfPublisherIfDeployed } from '../metrics';
+import { metadataFromHeaders, sourceRegionFromEdgePop } from '../server';
+
+describe('telemetry header lists', () => {
+  it('request headers are exactly the headers a browser sends', () => {
+    expect([...OXY_TELEMETRY_REQUEST_HEADERS]).toEqual([
+      OXY_ACTIVITY_ID_HEADER,
+      OXY_EDGE_REGION_HEADER,
+    ]);
+    expect(OXY_TELEMETRY_REQUEST_HEADERS).not.toContain(OXY_SOURCE_REGION_HEADER);
+  });
+
+  it('exposed headers are exactly the response headers a browser reads', () => {
+    expect([...OXY_TELEMETRY_EXPOSED_HEADERS]).toEqual([OXY_REGION_HEADER]);
+  });
+
+  it('the server reads the same headers the constants name', () => {
+    expect(
+      metadataFromHeaders({
+        [OXY_EDGE_REGION_HEADER.toLowerCase()]: 'MAD',
+        [OXY_ACTIVITY_ID_HEADER.toLowerCase()]: 'anonymous-runtime-a1',
+      }),
+    ).toEqual({ edgePop: 'mad', activityId: 'anonymous-runtime-a1' });
+  });
+});
+
+// The pre-change behaviour, copied verbatim from origin/main collector.ts
+// (middleware lines 119-124, instrumentTrafficFetch lines 200-202).
+const legacyInboundExcluded = (path: string): boolean =>
+  /^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|platform-infrastructure|infra-status)(?:\/|$)/.test(
+    path,
+  ) ||
+  path.startsWith('/internal/activity') ||
+  path.startsWith('/auth/service-token') ||
+  path.startsWith('/cdn-cgi/');
+const legacyOutboundExcluded = (pathname: string): boolean =>
+  pathname.startsWith('/internal/activity') ||
+  pathname.startsWith('/auth/service-token') ||
+  pathname === '/platform-infrastructure';
+
+const PATHS = [
+  '/',
+  '/users/me',
+  '/api/v1/users',
+  '/auth/session',
+  '/healthy',
+  '/readyz',
+  '/cdn-cgi',
+  '/health',
+  '/health/deep',
+  '/health?x=1',
+  '/api/health',
+  '/api/health/x',
+  '/ready',
+  '/api/ready',
+  '/live',
+  '/api/live',
+  '/platform-stats',
+  '/platform-stats/stream',
+  '/api/platform-stats',
+  '/platform-activity',
+  '/platform-activity/x',
+  '/api/platform-activity',
+  '/infra-status',
+  '/infra-status/x',
+  '/api/infra-status',
+  '/platform-infrastructure',
+  '/platform-infrastructure/',
+  '/platform-infrastructure/x',
+  '/api/platform-infrastructure',
+  '/api/platform-infrastructure/x',
+  '/platform-infrastructures',
+  '/api/api/health',
+  '/internal/activity',
+  '/internal/activity/batch',
+  '/internal/activityx',
+  '/auth/service-token',
+  '/auth/service-token/x',
+  '/auth/service-tokens',
+  '/cdn-cgi/',
+  '/cdn-cgi/trace',
+  '/v1/health',
+];
+
+describe('isObservedPath', () => {
+  it.each(PATHS)('%s matches the pre-change inbound behaviour', (path) => {
+    expect(isObservedPath(path, 'inbound')).toBe(!legacyInboundExcluded(path));
+  });
+
+  it.each(PATHS)('%s matches the pre-change outbound behaviour', (path) => {
+    expect(isObservedPath(path, 'outbound')).toBe(!legacyOutboundExcluded(path));
+  });
+
+  it('pins the excluded sets explicitly in both directions', () => {
+    const excluded = (direction: 'inbound' | 'outbound') =>
+      PATHS.filter((path) => !isObservedPath(path, direction));
+    expect(excluded('outbound')).toEqual([
+      '/platform-infrastructure',
+      '/internal/activity',
+      '/internal/activity/batch',
+      '/internal/activityx',
+      '/auth/service-token',
+      '/auth/service-token/x',
+      '/auth/service-tokens',
+    ]);
+    expect(excluded('inbound')).toEqual(PATHS.filter(legacyInboundExcluded));
+    // Excluded inbound only today; recorded outbound. Unifying is an owner decision.
+    expect(excluded('inbound').filter((path) => isObservedPath(path, 'outbound'))).toContain(
+      '/platform-stats',
+    );
+  });
+});
+
+describe('sourceRegionFromEdgePop', () => {
+  it('prefixes a PoP and passes absence through', () => {
+    expect(sourceRegionFromEdgePop('mad')).toBe('edge-mad');
+    expect(sourceRegionFromEdgePop(undefined)).toBeUndefined();
+    expect(sourceRegionFromEdgePop('')).toBeUndefined();
+  });
+});
+
+describe('createEmfPublisherIfDeployed', () => {
+  const options = { namespace: 'Oxy/Test', service: 'svc', write: () => {} };
+
+  it('returns null off ECS', () => {
+    expect(createEmfPublisherIfDeployed(options, {})).toBeNull();
+    expect(createEmfPublisherIfDeployed(options, { ECS_CONTAINER_METADATA_URI_V4: '' })).toBeNull();
+  });
+
+  it('returns a publisher on ECS', () => {
+    const publisher = createEmfPublisherIfDeployed(options, {
+      ECS_CONTAINER_METADATA_URI_V4: 'http://169.254.170.2/v4/task',
+    });
+    expect(publisher).not.toBeNull();
+    publisher?.stop();
+  });
+
+  it('reads process.env by default', () => {
+    const previous = process.env.ECS_CONTAINER_METADATA_URI_V4;
+    delete process.env.ECS_CONTAINER_METADATA_URI_V4;
+    try {
+      expect(createEmfPublisherIfDeployed(options)).toBeNull();
+    } finally {
+      if (previous !== undefined) process.env.ECS_CONTAINER_METADATA_URI_V4 = previous;
+    }
+  });
+});
+
+describe('instrumentTrafficFetch exclusion', () => {
+  it('skips control requests and still records outbound calls to inbound-excluded paths', async () => {
+    const { createTrafficCollector, instrumentTrafficFetch } = await import('../collector');
+    const published: unknown[][] = [];
+    const collector = createTrafficCollector(async (events) => {
+      published.push(events);
+    });
+    const fetcher = jest.fn(async () => new Response('ok')) as unknown as typeof fetch;
+    const observed = instrumentTrafficFetch(
+      fetcher,
+      collector,
+      'svc',
+      'us-west-2',
+      () => undefined,
+    );
+    await observed('https://example.com/internal/activity');
+    await observed('https://example.com/auth/service-token');
+    await observed('https://example.com/platform-infrastructure');
+    await collector.flush();
+    expect(published).toHaveLength(0);
+    // Recorded outbound today, though excluded inbound.
+    await observed('https://example.com/platform-stats');
+    await collector.flush();
+    expect(published).toHaveLength(1);
+  });
+});

package/src/browser.ts

@@ -60,6 +60,12 @@ function eligibleLocation(location: Pick<Location, 'hostname' | 'protocol'> | un
   );
 }
 
+/**
+ * @deprecated No Oxy repo constructs its own runtime: use the module-level
+ * `getBrowserActivityIdHeader`, `getBrowserEdgeRegionHeader` and
+ * `peekBrowserEdgeRegionHeader`. The factory remains the test seam. Removal from
+ * the public surface is planned for the next major.
+ */
 export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): BrowserTelemetry {
   let activityId: string | null = null;
   let activityIdCreatedAt = 0;
@@ -169,5 +175,10 @@ export const getBrowserEdgeRegionHeader = (): Promise<Record<string, string>> =>
 export const peekBrowserEdgeRegionHeader = (): Record<string, string> =>
   defaultBrowserTelemetry.peekEdgeRegionHeader();
 
+/**
+ * @deprecated Unused by any Oxy repo. `@oxy.so/core` sends
+ * `peekBrowserEdgeRegionHeader()` and `getBrowserActivityIdHeader()` per request.
+ * Removal is planned for the next major.
+ */
 export const getBrowserTelemetryHeaders = (): Promise<Record<string, string>> =>
   defaultBrowserTelemetry.getHeaders();