@oxy.so/telemetry 1.0.0 → 1.1.1

package/src/__tests__/collector.test.ts

@@ -0,0 +1,95 @@
+/** @jest-environment node */
+import { EventEmitter } from 'node:events';
+import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, trafficType, type TrafficAggregate } from '../collector';
+
+describe('ecosystem activity collector', () => {
+  it('reports all products independently of dashboard viewers and counts errors too', async () => {
+    const batches: TrafficAggregate[][] = [];
+    const collector = createTrafficCollector(async events => { batches.push(events); });
+    for (const service of ['website', 'mention', 'mercaria', 'alia', 'kaana']) {
+      const response = new EventEmitter();
+      trafficMiddleware(collector, service, 'us-west-2')({ path: '/api/files/private-id', headers: { 'cf-ray': 'example-NRT', authorization: 'secret' } }, response, () => {});
+      response.emit('finish');
+      response.emit('close');
+    }
+    await collector.flush();
+    expect(batches[0]).toHaveLength(10);
+    expect(batches[0].filter(event => event.direction === 'inbound')).toHaveLength(5);
+    expect(batches[0].every(event => event.activityType === 'media')).toBe(true);
+    expect(JSON.stringify(batches)).not.toMatch(/private-id|secret|authorization/);
+  });
+
+  it('keeps scope, direction and category independent for co-located internal services', async () => {
+    const batches: TrafficAggregate[][] = [];
+    const collector = createTrafficCollector(async events => { batches.push(events); });
+    const response = new EventEmitter();
+    const request = { path: '/v1/chat/completions', headers: { 'x-oxy-source-region': 'us-west-2' }, serviceApp: undefined as undefined | { appName: string } };
+    trafficMiddleware(collector, 'kaana', 'us-west-2')(request, response, () => { request.serviceApp = { appName: 'oxy-api' }; });
+    response.emit('finish');
+    await collector.flush();
+    expect(batches[0]).toEqual([
+      expect.objectContaining({ sourceRegion: 'us-west-2', targetRegion: 'us-west-2', sourceService: 'oxy-api', targetService: 'kaana', direction: 'inbound', scope: 'internal', activityType: 'ai' }),
+      expect.objectContaining({ sourceService: 'kaana', targetService: 'oxy-api', direction: 'outbound', scope: 'internal', activityType: 'ai' }),
+    ]);
+  });
+
+  it('does not fabricate a response on abort and excludes telemetry control traffic', async () => {
+    const batches: TrafficAggregate[][] = [];
+    const collector = createTrafficCollector(async events => { batches.push(events); });
+    for (const path of ['/health', '/api/ready', '/platform-stats/stream', '/internal/activity']) {
+      const response = new EventEmitter();
+      trafficMiddleware(collector, 'website', 'us-west-2')({ path, headers: {} }, response, () => {});
+      response.emit('finish');
+    }
+    const aborted = new EventEmitter();
+    trafficMiddleware(collector, 'mention', 'us-west-2')({ path: '/messages', headers: {} }, aborted, () => {});
+    aborted.emit('close');
+    await collector.flush();
+    expect(batches[0]).toHaveLength(1);
+    expect(batches[0][0].direction).toBe('inbound');
+  });
+
+  it('tracks real outgoing calls and only reports the response when one arrived', async () => {
+    const batches: TrafficAggregate[][] = [];
+    const collector = createTrafficCollector(async events => { batches.push(events); });
+    const fetcher = instrumentTrafficFetch(jest.fn(async () => new Response('ok', { headers: { 'X-Oxy-Region': 'eu-central-1' } })) as unknown as typeof fetch, collector, 'alia', 'us-west-2', url => url.hostname === 'api.oxy.so' ? { service: 'oxy-api', region: 'us-west-2' } : undefined);
+    await fetcher('https://api.oxy.so/v1/chat/completions');
+    await collector.flush();
+    expect(batches[0].map(event => event.direction)).toEqual(['outbound', 'inbound']);
+    expect(batches[0].every(event => event.scope === 'internal')).toBe(true);
+    expect(batches[0][0].targetRegion).toBe('eu-central-1');
+    expect(batches[0][1].sourceRegion).toBe('eu-central-1');
+    const failed = instrumentTrafficFetch(jest.fn(async () => { throw new Error('offline'); }) as unknown as typeof fetch, collector, 'alia', 'us-west-2', () => undefined);
+    await expect(failed('https://example.com/files')).rejects.toThrow('offline');
+    await collector.flush();
+    expect(batches[1]).toHaveLength(1);
+    expect(batches[1][0]).toMatchObject({ scope: 'external', direction: 'outbound', activityType: 'media' });
+  });
+
+  it('chunks a busy fleet into ingestible batches and preserves fetch extensions', async () => {
+    const batches: TrafficAggregate[][] = [];
+    const collector = createTrafficCollector(async events => { batches.push(events); });
+    for (let index = 0; index < 300; index++) collector.record({ region: 'us-west-2', service: `service-${index}`, scope: 'internal', direction: 'inbound', activityType: 'platform' });
+    await collector.flush();
+    expect(batches.map(batch => batch.length)).toEqual([256, 44]);
+    const preconnect = jest.fn();
+    const baseFetch = Object.assign(jest.fn(async () => new Response()), { preconnect }) as unknown as typeof fetch;
+    const wrapped = instrumentTrafficFetch(baseFetch, collector, 'website', 'us-west-2', () => undefined);
+    expect((wrapped as typeof baseFetch & { preconnect: unknown }).preconnect).toBe(preconnect);
+  });
+
+  it('keeps verified internal attribution when a request aborts', async () => {
+    const batches: TrafficAggregate[][] = [];
+    const collector = createTrafficCollector(async events => { batches.push(events); });
+    const response = new EventEmitter();
+    trafficMiddleware(collector, 'oxy-api', 'us-west-2')({ path: '/messages', headers: { 'x-oxy-source-region': 'eu-west-1' }, serviceApp: { appName: 'mention' } }, response, () => {});
+    response.emit('close');
+    await collector.flush();
+    expect(batches[0]).toEqual([expect.objectContaining({ scope: 'internal', direction: 'inbound', sourceRegion: 'eu-west-1', sourceService: 'mention' })]);
+  });
+
+  it('classifies versioned media and inference endpoints without retaining the path', () => {
+    expect(trafficType('/api/v1/uploads/private-id?token=secret')).toBe('media');
+    expect(trafficType('/v1/chat/completions')).toBe('ai');
+  });
+});

package/src/__tests__/edge.test.ts

@@ -0,0 +1,110 @@
+/** @jest-environment node */
+import { observeEdgeRequest, type EdgeActivityEnv } from '../edge';
+
+function setup(path = '/private-name.png?email=secret@example.com') {
+  const request = new Request(`https://example.com${path}`, { headers: { 'CF-Connecting-IP': '203.0.113.8', 'X-Oxy-Source-Region': 'eu-west-1', Authorization: 'private' } });
+  Object.assign(request, { cf: { colo: 'MAD', country: 'ES' } });
+  const tasks: Promise<unknown>[] = [];
+  const env: EdgeActivityEnv = { OXY_EDGE_ACTIVITY_ENABLED: 'true', OXY_EDGE_ACTIVITY_API_KEY: 'key', OXY_EDGE_ACTIVITY_API_SECRET: 'secret' };
+  const fetcher = jest.fn(async (input: RequestInfo | URL) => String(input).endsWith('service-token') ? Response.json({ token: 'token', expiresIn: 3600 }) : new Response(null, { status: 204 }));
+  return { request, env, tasks, fetcher, ctx: { waitUntil: (task: Promise<unknown>) => tasks.push(task) }, service: 'noted', onError: jest.fn() };
+}
+
+test('preserves the response stream, cache headers and media type without personal metadata', async () => {
+  const state = setup();
+  const response = new Response(new ReadableStream({ start(c) { c.enqueue(new TextEncoder().encode('image')); c.close(); } }), { headers: { 'Content-Type': 'image/png', 'Cache-Control': 'public,max-age=3600' } });
+  expect(await observeEdgeRequest({ ...state, next: () => response })).toBe(response);
+  expect(response.bodyUsed).toBe(false);
+  await Promise.all(state.tasks);
+  const calls = state.fetcher.mock.calls as unknown as [URL, RequestInit][];
+  expect(JSON.parse(String(calls[0][1].body))).toEqual({ apiKey: 'key', apiSecret: 'secret' });
+  const events = JSON.parse(String(calls[1][1].body));
+  expect(events).toHaveLength(2);
+  expect(events[0]).toMatchObject({ region: 'edge-mad', scope: 'external', direction: 'inbound', activityType: 'media', targetRegion: 'edge-mad' });
+  expect(events[1]).toMatchObject({ direction: 'outbound', sourceRegion: 'edge-mad' });
+  expect(events[0].sourceRegion).toBeUndefined();
+  expect(JSON.stringify(events)).not.toMatch(/private|secret|203\.0|example|email|eu-west/);
+  expect(await response.text()).toBe('image');
+});
+
+test('preserves handler errors and only reports received activity', async () => {
+  const state = setup(); const error = new Error('upstream');
+  await expect(observeEdgeRequest({ ...state, next: () => { throw error; } })).rejects.toBe(error);
+  await Promise.all(state.tasks);
+  const calls = state.fetcher.mock.calls as unknown as [URL, RequestInit][];
+  expect(JSON.parse(String(calls[1][1].body)).map((x: {direction:string}) => x.direction)).toEqual(['inbound']);
+});
+
+test.each(['/health', '/api/ready', '/internal/activity', '/auth/service-token', '/cdn-cgi/trace'])('excludes control route %s', async (path) => {
+  const state = setup(path); const response = new Response(null);
+  expect(await observeEdgeRequest({ ...state, next: () => response })).toBe(response);
+  expect(state.tasks).toHaveLength(0);
+});
+
+test('disabled bindings bypass publishing and missing enabled credentials report a fixed error', async () => {
+  const state = setup(); state.env = {};
+  await observeEdgeRequest({ ...state, next: () => new Response(null) });
+  expect(state.tasks).toHaveLength(0);
+  state.env.OXY_EDGE_ACTIVITY_ENABLED = 'true';
+  await observeEdgeRequest({ ...state, next: () => new Response(null) });
+  await Promise.all(state.tasks);
+  expect(state.onError).toHaveBeenCalledWith('Edge activity publication failed');
+  expect(state.fetcher).not.toHaveBeenCalled();
+});
+
+test('verified peer is internal independently of inbound/outbound', async () => {
+  const state = setup();
+  await observeEdgeRequest({ ...state, peer: {service:'mention', region:'us-west-2'}, next: () => new Response(null) });
+  await Promise.all(state.tasks);
+  const calls = state.fetcher.mock.calls as unknown as [URL, RequestInit][];
+  expect(JSON.parse(String(calls[1][1].body))).toEqual([
+    expect.objectContaining({scope:'internal', direction:'inbound', sourceRegion:'us-west-2', sourceService:'mention'}),
+    expect.objectContaining({scope:'internal', direction:'outbound', targetRegion:'us-west-2', targetService:'mention'}),
+  ]);
+});
+
+test('caches token values and invalidates on ingestion 401 without retrying a batch', async () => {
+  const state = setup();
+  const fetcher = jest.fn(async (input: RequestInfo | URL) => String(input).endsWith('service-token') ? Response.json({token:'token',expiresIn:3600}) : new Response(null, {status:401}));
+  for (let i=0;i<2;i++) { await observeEdgeRequest({...state, fetcher, next:()=>new Response(null)}); await Promise.all(state.tasks); }
+  expect(fetcher.mock.calls.map(([url])=>String(url))).toEqual(['https://api.oxy.so/auth/service-token','https://api.oxy.so/internal/activity','https://api.oxy.so/auth/service-token','https://api.oxy.so/internal/activity']);
+});
+
+test('unknown colo stays unknown even when caller spoofs geo headers', async () => {
+  const state = setup(); Object.assign(state.request, {cf:undefined});
+  await observeEdgeRequest({...state, credential:async()=>'injected', next:()=>new Response(null)}); await Promise.all(state.tasks);
+  const calls = state.fetcher.mock.calls as unknown as [URL, RequestInit][];
+  expect(calls).toHaveLength(1);
+  expect(JSON.parse(String(calls[0][1].body))[0].region).toBe('unknown');
+});
+
+test('reuses only a token value on later requests and refreshes after credential rotation', async () => {
+  const state = setup();
+  for (let i=0;i<2;i++) { await observeEdgeRequest({...state,next:()=>new Response(null)}); await Promise.all(state.tasks); }
+  expect(state.fetcher.mock.calls).toHaveLength(3);
+  state.env.OXY_EDGE_ACTIVITY_API_SECRET = 'rotated';
+  await observeEdgeRequest({...state,next:()=>new Response(null)}); await Promise.all(state.tasks);
+  expect(state.fetcher.mock.calls).toHaveLength(5);
+});
+
+test('bounds an injected credential that never resolves without delaying the response', async () => {
+  jest.useFakeTimers();
+  try {
+    const state = setup(); const response = new Response(null);
+    expect(await observeEdgeRequest({...state,credential:()=>new Promise(()=>{}),next:()=>response})).toBe(response);
+    await jest.advanceTimersByTimeAsync(4_000);
+    await Promise.all(state.tasks);
+    expect(state.onError).toHaveBeenCalledTimes(1);
+    expect(state.fetcher).not.toHaveBeenCalled();
+    expect(jest.getTimerCount()).toBe(0);
+  } finally { jest.useRealTimers(); }
+});
+
+test('bounds token response size and never publishes credentials in diagnostics', async () => {
+  const state = setup();
+  const fetcher = jest.fn(async()=>new Response('secret'.repeat(4000)));
+  await observeEdgeRequest({...state,fetcher,next:()=>new Response(null)});
+  await Promise.all(state.tasks);
+  expect(fetcher).toHaveBeenCalledTimes(1);
+  expect(state.onError).toHaveBeenCalledWith('Edge activity publication failed');
+});

package/src/__tests__/socket.test.ts

@@ -0,0 +1,118 @@
+/** @jest-environment node */
+import { EventEmitter } from 'node:events';
+import { observeTrafficSocket, socketTrafficType } from '../socket';
+import type { TrafficFlow } from '../collector';
+
+class TestSocket extends EventEmitter {
+  handshake = { headers: { 'cf-ray': 'anonymous-MAD', authorization: 'private' } };
+  nsp = { name: '/messages' };
+  incoming = new Set<(event: string) => void>();
+  outgoing = new Set<(event: string) => void>();
+  onAny(listener: (event: string) => void) { this.incoming.add(listener); }
+  onAnyOutgoing(listener: (event: string) => void) { this.outgoing.add(listener); }
+  offAny(listener: (event: string) => void) { this.incoming.delete(listener); }
+  offAnyOutgoing(listener: (event: string) => void) { this.outgoing.delete(listener); }
+}
+
+describe('socket traffic', () => {
+  it('records real application directions and strips event identifiers and payloads', () => {
+    const socket = new TestSocket();
+    const events: TrafficFlow[] = [];
+    observeTrafficSocket(socket, { record: event => events.push(event) }, 'syra', 'us-west-2');
+    socket.incoming.forEach(listener => listener('player:private-track-id'));
+    socket.outgoing.forEach(listener => listener('message:private-user-id'));
+    expect(events).toEqual([
+      expect.objectContaining({ scope: 'external', direction: 'inbound', sourceRegion: 'edge-mad', targetRegion: 'us-west-2', activityType: 'media' }),
+      expect.objectContaining({ scope: 'external', direction: 'outbound', sourceRegion: 'us-west-2', targetRegion: 'edge-mad', activityType: 'communication' }),
+    ]);
+    expect(JSON.stringify(events)).not.toMatch(/private|authorization|track-id|user-id/);
+    socket.emit('disconnect');
+    expect(socket.incoming.size + socket.outgoing.size).toBe(0);
+  });
+
+  it('uses only verified peer metadata for internal traffic and reads it at event time', () => {
+    const socket = new TestSocket();
+    const events: TrafficFlow[] = [];
+    let peer: { service: string; region: string } | undefined;
+    const stop = observeTrafficSocket(socket, { record: event => events.push(event) }, 'alia', 'us-west-2', { getPeer: () => peer });
+    peer = { service: 'mention', region: 'eu-west-1' };
+    socket.incoming.forEach(listener => listener('agent:update'));
+    expect(events[0]).toMatchObject({ scope: 'internal', sourceService: 'mention', sourceRegion: 'eu-west-1', activityType: 'ai' });
+    stop(); stop();
+    expect(socket.listenerCount('disconnect')).toBe(0);
+  });
+
+  it('does not observe dashboard control namespaces or create events merely for connecting', () => {
+    const socket = new TestSocket();
+    const record = jest.fn();
+    socket.nsp.name = '/platform-activity';
+    observeTrafficSocket(socket, { record }, 'oxy-api', 'us-west-2');
+    expect(socket.incoming.size + socket.outgoing.size).toBe(0);
+    expect(record).not.toHaveBeenCalled();
+    expect(socketTrafficType('arbitrary-private-value')).toBe('platform');
+  });
+});
+
+describe('real Socket.IO transport', () => {
+  it('observes events and namespace broadcasts without inventing acknowledgement traffic', async () => {
+    const { Server } = await import('socket.io');
+    const { io } = await import('socket.io-client');
+    const { createServer } = await import('node:http');
+    const server = createServer();
+    const sockets = new Server(server);
+    const events: TrafficFlow[] = [];
+    sockets.on('connection', socket => {
+      observeTrafficSocket(socket, { record: flow => events.push(flow) }, 'syra', 'us-west-2');
+      socket.on('player:seek', (_position, acknowledge) => {
+        acknowledge('ok');
+        sockets.emit('player:state', { privateTrackId: 'never-published' });
+      });
+    });
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') throw new Error('Missing listener');
+    const client = io(`http://127.0.0.1:${address.port}`, { transports: ['websocket'], extraHeaders: { 'X-Oxy-Edge-Region': 'NRT' } });
+    try {
+      await new Promise<void>((resolve, reject) => { client.once('connect', resolve); client.once('connect_error', reject); });
+      const received = new Promise<void>(resolve => client.once('player:state', () => resolve()));
+      await client.emitWithAck('player:seek', 42);
+      await received;
+      expect(events).toHaveLength(2);
+      expect(events.map(flow => [flow.direction, flow.scope, flow.activityType])).toEqual([
+        ['inbound', 'external', 'media'], ['outbound', 'external', 'media'],
+      ]);
+      expect(events[0].sourceRegion).toBe('edge-nrt');
+      expect(events[1].targetRegion).toBe('edge-nrt');
+      expect(JSON.stringify(events)).not.toContain('never-published');
+    } finally {
+      client.disconnect();
+      await new Promise<void>(resolve => sockets.close(() => resolve()));
+    }
+  });
+});
+
+describe('raw WebSocket transport', () => {
+  it('preserves send callbacks, synchronous errors and method cleanup without reading messages', async () => {
+    const { observeTrafficWebSocket } = await import('../socket');
+    const events: TrafficFlow[] = [];
+    const original = jest.fn((_data: unknown, callback: (error?: Error) => void) => callback());
+    const socket = Object.assign(new EventEmitter(), { readyState: 1, send: original });
+    const stop = observeTrafficWebSocket(socket, { record: flow => events.push(flow) }, 'alia', 'us-west-2', {
+      activityType: 'ai', getPeer: () => ({ service: 'alia-integrations', region: 'eu-west-1' }),
+    });
+    const callback = jest.fn();
+    socket.send({ privateBody: 'not-recorded' }, callback);
+    socket.emit('message', Buffer.from('private-message'));
+    expect(original).toHaveBeenCalledWith({ privateBody: 'not-recorded' }, callback);
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(events.map(flow => flow.direction)).toEqual(['outbound', 'inbound']);
+    expect(events.every(flow => flow.scope === 'internal' && flow.activityType === 'ai')).toBe(true);
+    expect(JSON.stringify(events)).not.toMatch(/private|not-recorded/);
+    original.mockImplementationOnce(() => { throw new Error('send failed'); });
+    expect(() => socket.send('', callback)).toThrow('send failed');
+    expect(events).toHaveLength(2);
+    stop(); stop();
+    expect(socket.send).toBe(original);
+    expect(socket.listenerCount('message')).toBe(0);
+  });
+});

package/src/browser.ts

@@ -2,6 +2,7 @@ import { OXY_ACTIVITY_ID_HEADER, OXY_EDGE_REGION_HEADER } from './index.js';
 
 export const DEFAULT_ACTIVITY_ID_ROTATION_MS = 5 * 60 * 1_000;
 export const DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1_000;
+export const DEFAULT_EDGE_CACHE_MS = 15_000;
 
 interface TraceResponse {
   ok: boolean;
@@ -11,6 +12,7 @@ interface TraceResponse {
 export interface BrowserTelemetryOptions {
   activityIdRotationMs?: number;
   edgeTraceTimeoutMs?: number;
+  edgeCacheMs?: number;
   now?: () => number;
   crypto?: Pick<Crypto, 'getRandomValues' | 'randomUUID'>;
   location?: Pick<Location, 'hostname' | 'protocol'>;
@@ -45,6 +47,7 @@ export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): B
   let activityId: string | null = null;
   let activityIdCreatedAt = 0;
   let edgePopPromise: Promise<string | null> | null = null;
+  let edgePopReadAt = -Infinity;
 
   const getActivityIdHeader = (): Record<string, string> => {
     const hasInjectedBrowser = Boolean(options.location);
@@ -79,7 +82,11 @@ export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): B
   };
 
   const getEdgeRegionHeader = async (): Promise<Record<string, string>> => {
-    edgePopPromise ??= discoverEdgePop();
+    const now = (options.now ?? Date.now)();
+    if (!edgePopPromise || now < edgePopReadAt || now - edgePopReadAt >= (options.edgeCacheMs ?? DEFAULT_EDGE_CACHE_MS)) {
+      edgePopReadAt = now;
+      edgePopPromise = discoverEdgePop();
+    }
     const edgePop = await edgePopPromise;
     return edgePop ? { [OXY_EDGE_REGION_HEADER]: edgePop } : {};
   };

package/src/collector.ts

@@ -0,0 +1,192 @@
+import { metadataFromHeaders, 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;
+}
+
+const TYPES: Record<string, TrafficType> = {
+  auth: 'identity', session: 'identity', users: 'identity', profiles: 'identity', accounts: 'identity',
+  ai: 'ai', inference: 'ai', models: 'ai', chat: 'ai', completions: 'ai',
+  stream: 'media', tracks: 'media', episodes: 'media', recordings: 'media', rooms: 'media',
+  messages: 'communication', notifications: 'communication', mail: 'communication',
+  media: 'media', files: 'media', assets: 'media', upload: 'media', uploads: 'media', cdn: 'media', storage: 'media', images: 'media', audio: 'media', videos: 'media',
+};
+export function trafficType(path: string): TrafficType {
+  const parts = path.split('?')[0].split('/').filter(Boolean);
+  if (parts[0] === 'alia') parts.shift();
+  if (parts[0] === 'api') parts.shift();
+  if (/^v\d+$/.test(parts[0] ?? '')) parts.shift();
+  return TYPES[parts[0] ?? ''] ?? 'platform';
+}
+
+export function createTrafficCollector(publish: (events: TrafficAggregate[]) => Promise<unknown>, now = Date.now) {
+  const pending = new Map<string, { flow: TrafficFlow; requests: number; startedAt: number }>();
+  let flushing: Promise<void> | null = null;
+  return {
+    record(flow: TrafficFlow) {
+      const key = JSON.stringify(flow);
+      const existing = pending.get(key);
+      if (existing) existing.requests++;
+      else if (pending.size < 512) pending.set(key, { flow, requests: 1, startedAt: now() });
+    },
+    async flush() {
+      while (flushing) await flushing;
+      if (pending.size === 0) return;
+      const emittedAt = new Date(now()).toISOString();
+      const events = [...pending.values()].map(({ flow, requests, startedAt }) => ({ ...flow, requests, windowStartedAt: new Date(startedAt).toISOString(), emittedAt }));
+      pending.clear();
+      flushing = (async () => {
+        for (let offset = 0; offset < events.length; offset += 256) await publish(events.slice(offset, offset + 256));
+      })();
+      try { await flushing; } finally { flushing = null; }
+    },
+  };
+}
+
+interface HttpRequest {
+  headers: TelemetryHeaders;
+  path?: string;
+  url?: string;
+  serviceApp?: { appName?: string };
+}
+interface HttpResponse { once(event: string, listener: () => void): unknown; setHeader?(name: string, value: string): unknown }
+
+export function trafficMiddleware(
+  collector: Pick<ReturnType<typeof createTrafficCollector>, 'record'>,
+  service: string,
+  region: string,
+) {
+  return (request: HttpRequest, response: HttpResponse, next: () => void): void => {
+    response.setHeader?.('X-Oxy-Region', region);
+    const path = request.path ?? request.url ?? '/';
+    // Never report collection itself, probes or the dashboard transport.
+    if (/^\/(?: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/')) { next(); return; }
+    const { edgePop } = metadataFromHeaders(request.headers);
+    const activityType = trafficType(path);
+    let finished = false;
+    const inboundFlow = (): TrafficFlow => {
+      // Read service identity AFTER the route's shared auth middleware resolved it.
+      const name = request.serviceApp?.appName?.toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40);
+      const internal = Boolean(name);
+      const forwardedRegion = request.headers['x-oxy-source-region'];
+      const peerRegion = internal ? normalizeInfrastructureRegion(forwardedRegion) : edgePop ? `edge-${edgePop}` : undefined;
+      return { region, service, activityType, scope: internal ? 'internal' : 'external', direction: 'inbound', sourceRegion: peerRegion, targetRegion: region, sourceService: name, targetService: service };
+    };
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      const flow = inboundFlow();
+      collector.record(flow);
+      collector.record({ ...flow, direction: 'outbound', sourceRegion: region, targetRegion: flow.sourceRegion, sourceService: service, targetService: flow.sourceService });
+    };
+    response.once('finish', finish);
+    // Failed/aborted requests are still real inbound activity. Do not invent a
+    // completed outbound response when the connection closes prematurely.
+    response.once('close', () => {
+      if (finished) return;
+      finished = true;
+      collector.record(inboundFlow());
+    });
+    next();
+  };
+}
+
+export interface ServiceEndpoint { service: string; region: string }
+export function instrumentTrafficFetch(
+  fetcher: typeof fetch,
+  collector: Pick<ReturnType<typeof createTrafficCollector>, 'record'>,
+  service: string,
+  region: string,
+  resolveEndpoint: (url: URL) => ServiceEndpoint | undefined,
+): typeof fetch {
+  return Object.assign(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
+    // Collection/auth control traffic cannot generate a feedback loop.
+    if (url.pathname.startsWith('/internal/activity') || url.pathname.startsWith('/auth/service-token') || url.pathname === '/platform-infrastructure') return fetcher(input, init);
+    const peer = resolveEndpoint(url);
+    const flow: TrafficFlow = {
+      service, region, scope: peer ? 'internal' : 'external', direction: 'outbound',
+      activityType: trafficType(url.pathname), sourceRegion: region, targetRegion: peer?.region,
+      sourceService: service, targetService: peer?.service,
+    };
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    if (peer) headers.set('X-Oxy-Source-Region', region);
+    let response: Response;
+    try { response = await fetcher(input, { ...init, headers }); }
+    catch (error) { collector.record({ ...flow, targetRegion: undefined }); throw error; }
+    const targetRegion = peer ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined) : undefined;
+    collector.record({ ...flow, targetRegion });
+    collector.record({ ...flow, direction: 'inbound', sourceRegion: targetRegion, targetRegion: region, sourceService: peer?.service, targetService: service });
+    return response;
+  }, fetcher) as typeof fetch;
+}
+
+// Exact deployed API hosts; an arbitrary caller-supplied hostname cannot claim
+// to be an internal service. Region is infrastructure metadata, never IP geo.
+const OXY_API_SERVICES: Record<string, string> = {
+  'api.oxy.so': 'oxy-api', 'api.website.oxy.so': 'website',
+  'website-api.oxy.so': 'website', 'api.mention.earth': 'mention',
+  'api.mercaria.co': 'mercaria', 'api.alia.onl': 'alia', 'kaana.ai': 'kaana',
+  'api.homiio.com': 'homiio', 'api.syra.fm': 'syra',
+  'mention.earth': 'mention', 'mcp.mention.earth': 'mention-mcp',
+  'api.clarity.surf': 'clarity', 'api.peable.to': 'peable',
+  'api.crowdsource.oxy.so': 'crowdsource', 'api.moovo.now': 'moovo',
+  'api.allo.you': 'allo', 'api.noted.oxy.so': 'noted', 'api.schedio.app': 'schedio', 'api.tnp.network': 'tnp-api',
+};
+export function resolveOxyServiceEndpoint(url: URL): ServiceEndpoint | undefined {
+  const service = OXY_API_SERVICES[url.hostname];
+  return url.protocol === 'https:' && service ? { service, region: 'us-west-2' } : undefined;
+}
+
+const REGION_LOCATIONS: Record<string, { label: string; coordinates: [number, number] }> = {
+  'us-west-2': { label: 'Oregon', coordinates: [-122.6765, 45.5231] },
+  'us-west-1': { label: 'Northern California', coordinates: [-121.89, 37.34] },
+  'us-east-1': { label: 'Northern Virginia', coordinates: [-77.49, 39.04] },
+  'us-east-2': { label: 'Ohio', coordinates: [-82.99, 39.96] },
+  'eu-west-1': { label: 'Ireland', coordinates: [-6.26, 53.35] },
+  'eu-west-2': { label: 'London', coordinates: [-0.1276, 51.5072] },
+  'eu-west-3': { label: 'Paris', coordinates: [2.3522, 48.8566] },
+  'eu-central-1': { label: 'Frankfurt', coordinates: [8.6821, 50.1109] },
+  'eu-central-2': { label: 'Zurich', coordinates: [8.54, 47.38] },
+  'eu-north-1': { label: 'Stockholm', coordinates: [18.07, 59.33] },
+  'eu-south-1': { label: 'Milan', coordinates: [9.19, 45.46] },
+  'eu-south-2': { label: 'Spain', coordinates: [-0.89, 41.65] },
+  'ap-northeast-1': { label: 'Tokyo', coordinates: [139.69, 35.69] },
+  'ap-northeast-2': { label: 'Seoul', coordinates: [126.98, 37.57] },
+  'ap-northeast-3': { label: 'Osaka', coordinates: [135.5, 34.69] },
+  'ap-southeast-1': { label: 'Singapore', coordinates: [103.82, 1.35] },
+  'ap-southeast-2': { label: 'Sydney', coordinates: [151.21, -33.87] },
+  'ap-southeast-3': { label: 'Jakarta', coordinates: [106.85, -6.21] },
+  'ap-southeast-4': { label: 'Melbourne', coordinates: [144.96, -37.81] },
+  'ap-south-1': { label: 'Mumbai', coordinates: [72.88, 19.08] },
+  'ap-south-2': { label: 'Hyderabad', coordinates: [78.49, 17.38] },
+  'ap-east-1': { label: 'Hong Kong', coordinates: [114.17, 22.32] },
+  'ca-central-1': { label: 'Canada', coordinates: [-73.57, 45.5] },
+  'ca-west-1': { label: 'Calgary', coordinates: [-114.07, 51.05] },
+  'sa-east-1': { label: 'São Paulo', coordinates: [-46.63, -23.55] },
+  'af-south-1': { label: 'Cape Town', coordinates: [18.42, -33.92] },
+  'me-south-1': { label: 'Bahrain', coordinates: [50.59, 26.22] },
+  'me-central-1': { label: 'UAE', coordinates: [54.37, 24.45] },
+  'il-central-1': { label: 'Tel Aviv', coordinates: [34.78, 32.09] },
+};
+export function infrastructureLocation(region: string) { return REGION_LOCATIONS[region]; }
+
+export function normalizeInfrastructureRegion(value: unknown): string | undefined {
+  return typeof value === 'string' && /^[a-z]{2}(?:-[a-z]+)+-\d$/.test(value) ? value : undefined;
+}