@oxy.so/telemetry 2.1.0 → 2.2.0

package/README.md

@@ -6,7 +6,8 @@ Redis, React, React Native or Expo.
 
 ## Entry points
 
-- `@oxy.so/telemetry` — shared header names and aggregate interfaces.
+- `@oxy.so/telemetry` — shared header names, the CORS header lists and the wire
+  types (`TrafficAggregate`, `ActivityAggregate`, `InfrastructureSnapshot`).
 - `@oxy.so/telemetry/browser` — ephemeral browser metadata.
 - `@oxy.so/telemetry/collector` — bounded HTTP/custom-transport flow aggregation.
 - `@oxy.so/telemetry/server` — pure validation, route bucketing and cardinality
@@ -20,12 +21,19 @@ side effects.
 ## Browser metadata
 
 ```ts
-import { getBrowserTelemetryHeaders } from '@oxy.so/telemetry/browser';
+import { getBrowserActivityIdHeader, peekBrowserEdgeRegionHeader } from '@oxy.so/telemetry/browser';
 
-const headers = await getBrowserTelemetryHeaders();
+const headers = { ...peekBrowserEdgeRegionHeader(), ...getBrowserActivityIdHeader() };
 await fetch('https://api.oxy.so/session/status', { headers });
 ```
 
+This is what `@oxy.so/core` sends on every request: the peek never waits on the
+trace. `getBrowserEdgeRegionHeader()` is the awaiting variant.
+
+A CORS allow-list for these headers is `OXY_TELEMETRY_REQUEST_HEADERS` (from the
+root entry), and `OXY_TELEMETRY_EXPOSED_HEADERS` for `Access-Control-Expose-Headers`;
+import them instead of repeating the header names.
+
 `X-Oxy-Activity-Id` is generated in memory for the current page runtime and
 rotates every five minutes. It is not placed in a cookie, local storage,
 session storage, IndexedDB or a URL. Closing or reloading the page loses it.
@@ -35,34 +43,32 @@ from the same-origin `/cdn-cgi/trace` endpoint. The helper reads no IP field and
 returns, logs and persists none of the rest of the trace response. Discovery is
 cached for 15 seconds per runtime (including failed discovery), has a one-second timeout and is disabled on loopback.
 
-Use `createBrowserTelemetry()` to create an isolated runtime or inject clock,
-crypto, location and trace-fetch dependencies in tests.
+`createBrowserTelemetry()` builds an isolated runtime with injected clock,
+crypto, location and trace-fetch dependencies; it is the test seam.
 
 ## Server primitives
 
 ```ts
 import {
-  activityFlow,
   metadataFromHeaders,
   presenceKeys,
-  serviceFromPath,
-  type ActivityCardinalityAdapter,
+  sourceRegionFromEdgePop,
 } from '@oxy.so/telemetry/server';
 
 const metadata = metadataFromHeaders(request.headers);
-const sourceRegion = metadata.edgePop ? `edge-${metadata.edgePop}` : undefined;
-const flow = activityFlow(sourceRegion, serviceFromPath(request.path));
+const sourceRegion = sourceRegionFromEdgePop(metadata.edgePop); // 'edge-mad' | undefined
 const keys = sourceRegion ? presenceKeys(sourceRegion, Date.now()) : [];
 ```
 
 Validation accepts a three-letter PoP and a 16–64 character opaque activity ID.
-It ignores IP and forwarding headers. `serviceFromPath` keeps only a bounded,
-static first route segment, so IDs and full paths cannot enter aggregates.
-
-`ActivityCardinalityAdapter` describes the minimal storage boundary for an
-implementation such as Redis HyperLogLog. This package does not instantiate a
+It ignores IP and forwarding headers. This package does not instantiate a
 store, keep server-global maps, start timers or send realtime events.
 
+`serviceFromPath`, `activityFlow`, `presenceBucket`, `ActivityCardinalityAdapter`,
+`ActivityBucket`, `DEFAULT_ACTIVE_CLIENT_WINDOW_MS`, `getBrowserTelemetryHeaders`
+and `createBrowserTelemetry` are deprecated: nothing in Oxy uses them and they go in
+the next major.
+
 ## Active-client definition
 
 An active client is one distinct ephemeral activity ID observed for an edge PoP
@@ -106,8 +112,10 @@ follow the actual movement, even when two services share one region.
 identity after route authentication. `instrumentTrafficFetch` observes actual
 outbound calls; internal destination regions come from the peer's `X-Oxy-Region`
 response, not a guessed IP location. Unlocated peers remain unlocated. Health,
-telemetry collection, infrastructure snapshots and service-token minting are
-excluded from observation where applicable to prevent control traffic feedback.
+telemetry collection, infrastructure snapshots, service-token minting and
+`/cdn-cgi/` are excluded from observation to prevent control traffic feedback;
+`isObservedPath(path, direction)` (reading the `UNOBSERVED_PATHS` table) is the one predicate, so an adapter that does its own
+interception imports it instead of copying a pattern.
 Custom transports can call the collector's `record` method explicitly.
 
 Each collector retains at most 512 distinct pending flows and publishes chunks
@@ -116,7 +124,8 @@ durable retry queue. These are live operational observations, not billing or
 lossless historical request totals. No dashboard viewer is needed to collect.
 
 Realtime transport publishes aggregate buckets, not individual metadata. A
-socket event may carry `ActivityAggregate`: request count, approximate active
+socket event carries `ActivityAggregate` (a `TrafficAggregate` plus
+`activeClients`; the infrastructure snapshot is `InfrastructureSnapshot`): request count, approximate active
 clients, source/target regions, service and window timestamps. Transport and
 fan-out are application concerns and intentionally absent from this package.
 
@@ -131,11 +140,15 @@ installed in each service before this can represent the whole ecosystem.
 The authenticated publisher is `createEcosystemTraffic` from `@oxy.so/core/server`.
 It exposes HTTP middleware, `wrapFetch`, `record` for explicit transport events,
 and `stop` for graceful removal. It requires a known infrastructure region (or
-explicit infrastructure coordinates) and one of three ways to authenticate: an
-`OXY_ACTIVITY_API_KEY`/`OXY_ACTIVITY_API_SECRET` pair, an
-`OXY_SERVICE_API_KEY`/`OXY_SERVICE_API_SECRET` pair, or no credential at all
-where the process can attest its workload identity (ADR 0026). Credentials, user
-metadata and paths never enter public snapshots.
+explicit infrastructure coordinates) and registered temporary workload identity
+for own service publication ([ADR 0049](../../docs/adr/0049-first-party-platform-authority.md)).
+The shared OxyServer performs attestation and live binding checks. A process can
+supply `workloadCredentials` from `createAwsWorkloadCredentialProvider()`
+(`@oxy.so/core/server/aws`) for the supported temporary AWS provider chain.
+There is no activity-key or service-key fallback for own publication. External
+customer API credentials remain separate and do not become first-party authority.
+Credentials, user metadata and paths never enter public snapshots. Activity's
+internal/external `scope` field classifies traffic; it is not an OAuth permission.
 
 ## Operational metrics (CloudWatch EMF)
 
@@ -166,6 +179,27 @@ Route, method, table and every other label stay plain properties on the line:
 `maxSeries` (default 2000) series are held per interval; past that, new series
 fold into one whose labels read `other`.
 
+On ECS only, `createEmfPublisherIfDeployed(options)` returns the same publisher
+and `null` elsewhere (it checks `ECS_CONTAINER_METADATA_URI_V4`), so a service
+does not repeat that gate.
+
+### Conformance fixture
+
+`fixtures/emf-golden.json` is the cross-language contract for the EMF line format.
+Each case holds a metric `definition`, `service`, `namespace`, a fixed `now`
+(the line's `Timestamp`), optional `maxSeries`, the `observations`
+(`{labels, value}`; the strings `"NaN"`, `"Infinity"` and `"-Infinity"` stand for
+the non-finite numbers JSON cannot carry) and the `expectedLines` the publisher
+must write on flush, in series first-seen order. Lines are compared as parsed
+JSON, not as bytes. `src/__tests__/emfGolden.test.ts` runs every case through the
+real publisher.
+
+Kaana's Go `internal/emf` must consume the same file (a vendored copy that a
+Kaana test keeps byte-identical to this one) and pass every case; change the
+fixture here first. Label values are truncated by UTF-16 code units, so a Go
+implementation counts UTF-16 units, not bytes or runes. The fixture avoids a cut
+inside a surrogate pair, whose result is a lone surrogate that UTF-8 cannot carry.
+
 ## Development
 
 ```bash

package/dist/cjs/browser.js

@@ -30,6 +30,12 @@ function eligibleLocation(location) {
         location.hostname !== '127.0.0.1' &&
         location.hostname !== '[::1]');
 }
+/**
+ * @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.
+ */
 function createBrowserTelemetry(options = {}) {
     let activityId = null;
     let activityIdCreatedAt = 0;
@@ -125,5 +131,10 @@ const getBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.getEdgeRegionHe
 exports.getBrowserEdgeRegionHeader = getBrowserEdgeRegionHeader;
 const peekBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.peekEdgeRegionHeader();
 exports.peekBrowserEdgeRegionHeader = peekBrowserEdgeRegionHeader;
+/**
+ * @deprecated Unused by any Oxy repo. `@oxy.so/core` sends
+ * `peekBrowserEdgeRegionHeader()` and `getBrowserActivityIdHeader()` per request.
+ * Removal is planned for the next major.
+ */
 const getBrowserTelemetryHeaders = () => defaultBrowserTelemetry.getHeaders();
 exports.getBrowserTelemetryHeaders = getBrowserTelemetryHeaders;

package/dist/cjs/collector.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNOBSERVED_PATHS = void 0;
 exports.trafficType = trafficType;
+exports.isObservedPath = isObservedPath;
 exports.createTrafficCollector = createTrafficCollector;
 exports.trafficMiddleware = trafficMiddleware;
 exports.instrumentTrafficFetch = instrumentTrafficFetch;
 exports.resolveOxyServiceEndpoint = resolveOxyServiceEndpoint;
 exports.infrastructureLocation = infrastructureLocation;
 exports.normalizeInfrastructureRegion = normalizeInfrastructureRegion;
+const index_js_1 = require("./index.js");
 const server_js_1 = require("./server.js");
 const TYPES = {
     auth: 'identity',
@@ -48,6 +51,35 @@ function trafficType(path) {
         parts.shift();
     return TYPES[parts[0] ?? ''] ?? 'platform';
 }
+/**
+ * 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.
+ */
+exports.UNOBSERVED_PATHS = [
+    {
+        directions: 'inbound',
+        matches: (path) => /^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|infra-status)(?:\/|$)/.test(path),
+    },
+    {
+        directions: 'inbound',
+        matches: (path) => /^\/(?:api\/)?platform-infrastructure(?:\/|$)/.test(path),
+    },
+    { directions: 'outbound', matches: (path) => path === '/platform-infrastructure' },
+    { directions: 'both', matches: (path) => path.startsWith('/internal/activity') },
+    { directions: 'both', matches: (path) => path.startsWith('/auth/service-token') },
+    { directions: 'inbound', matches: (path) => path.startsWith('/cdn-cgi/') },
+];
+/**
+ * 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.
+ */
+function isObservedPath(path, direction) {
+    return !exports.UNOBSERVED_PATHS.some((entry) => (entry.directions === 'both' || entry.directions === direction) && entry.matches(path));
+}
 function createTrafficCollector(publish, now = Date.now) {
     const pending = new Map();
     let flushing = null;
@@ -88,13 +120,10 @@ function createTrafficCollector(publish, now = Date.now) {
 }
 function trafficMiddleware(collector, service, region) {
     return (request, response, next) => {
-        response.setHeader?.('X-Oxy-Region', region);
+        response.setHeader?.(index_js_1.OXY_REGION_HEADER, 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/')) {
+        if (!isObservedPath(path, 'inbound')) {
             next();
             return;
         }
@@ -108,12 +137,10 @@ function trafficMiddleware(collector, service, region) {
                 .replace(/[^a-z0-9-]/g, '-')
                 .slice(0, 40);
             const internal = Boolean(name);
-            const forwardedRegion = request.headers['x-oxy-source-region'];
+            const forwardedRegion = request.headers[index_js_1.OXY_SOURCE_REGION_HEADER.toLowerCase()];
             const peerRegion = internal
                 ? normalizeInfrastructureRegion(forwardedRegion)
-                : edgePop
-                    ? `edge-${edgePop}`
-                    : undefined;
+                : (0, server_js_1.sourceRegionFromEdgePop)(edgePop);
             return {
                 region,
                 service,
@@ -157,9 +184,7 @@ function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndp
     return Object.assign(async (input, init) => {
         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')
+        if (!isObservedPath(url.pathname, 'outbound'))
             return fetcher(input, init);
         const peer = resolveEndpoint(url);
         const flow = {
@@ -175,7 +200,7 @@ function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndp
         };
         const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
         if (peer)
-            headers.set('X-Oxy-Source-Region', region);
+            headers.set(index_js_1.OXY_SOURCE_REGION_HEADER, region);
         let response;
         try {
             response = await fetcher(input, { ...init, headers });
@@ -185,7 +210,7 @@ function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndp
             throw error;
         }
         const targetRegion = peer
-            ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined)
+            ? normalizeInfrastructureRegion(response.headers.get(index_js_1.OXY_REGION_HEADER) ?? undefined)
             : undefined;
         collector.record({ ...flow, targetRegion });
         collector.record({
@@ -203,11 +228,12 @@ function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndp
 // to be an internal service. Region is infrastructure metadata, never IP geo.
 const OXY_API_SERVICES = {
     'api.oxy.so': 'oxy-api',
-    'api.website.oxy.so': 'website',
     'website-api.oxy.so': 'website',
     'api.mention.earth': 'mention',
     'api.mercaria.co': 'mercaria',
+    // Old Alia app builds still call it; goes when api.alia.onl is retired (Gemies ADR 0034).
     'api.alia.onl': 'alia',
+    'api.gemies.ai': 'gemies',
     'kaana.ai': 'kaana',
     'api.homiio.com': 'homiio',
     'api.syra.fm': 'syra',

package/dist/cjs/index.js

@@ -1,5 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OXY_EDGE_REGION_HEADER = exports.OXY_ACTIVITY_ID_HEADER = void 0;
+exports.OXY_TELEMETRY_EXPOSED_HEADERS = exports.OXY_TELEMETRY_REQUEST_HEADERS = exports.OXY_SOURCE_REGION_HEADER = exports.OXY_REGION_HEADER = exports.OXY_EDGE_REGION_HEADER = exports.OXY_ACTIVITY_ID_HEADER = void 0;
+/** Request header a browser sends: the ephemeral anonymous activity ID. */
 exports.OXY_ACTIVITY_ID_HEADER = 'X-Oxy-Activity-Id';
+/** Request header a browser sends: the three-letter Cloudflare PoP code. */
 exports.OXY_EDGE_REGION_HEADER = 'X-Oxy-Edge-Region';
+/** Response header a reporting service sets: the region that processed the request. */
+exports.OXY_REGION_HEADER = 'X-Oxy-Region';
+/** Request header one Oxy service sends another: the caller's infrastructure region. */
+exports.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.
+ */
+exports.OXY_TELEMETRY_REQUEST_HEADERS = Object.freeze([
+    exports.OXY_ACTIVITY_ID_HEADER,
+    exports.OXY_EDGE_REGION_HEADER,
+]);
+/**
+ * Response headers a browser client may need to read
+ * (`Access-Control-Expose-Headers`).
+ */
+exports.OXY_TELEMETRY_EXPOSED_HEADERS = Object.freeze([exports.OXY_REGION_HEADER]);

package/dist/cjs/metrics.js

@@ -27,6 +27,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HTTP_RATE_LIMITED = exports.HTTP_REQUEST_LATENCY = void 0;
 exports.statusClass = statusClass;
+exports.createEmfPublisherIfDeployed = createEmfPublisherIfDeployed;
 exports.createEmfPublisher = createEmfPublisher;
 /** One HTTP request: SampleCount is the request count, percentiles the latency. */
 exports.HTTP_REQUEST_LATENCY = {
@@ -102,6 +103,15 @@ function seriesKey(metric, labels) {
 function defaultWrite(line) {
     globalThis.process?.stdout?.write?.(`${line}\n`);
 }
+/** Set by ECS on every task: the one reliable signal that `awslogs` is capturing stdout. */
+const ECS_METADATA_ENV = 'ECS_CONTAINER_METADATA_URI_V4';
+/**
+ * `createEmfPublisher` on ECS, `null` everywhere else (a laptop, CI, a test):
+ * the gate oxy-api and Mention each repeated. `env` is injectable for tests.
+ */
+function createEmfPublisherIfDeployed(options, env = globalThis.process?.env ?? {}) {
+    return env[ECS_METADATA_ENV] ? createEmfPublisher(options) : null;
+}
 function createEmfPublisher(options) {
     const flushIntervalMs = options.flushIntervalMs ?? 60000;
     const maxSeries = options.maxSeries ?? 2000;

package/dist/cjs/server.js

@@ -3,12 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ACTIVE_CLIENT_WINDOW_MS = exports.DEFAULT_PRESENCE_BUCKET_MS = void 0;
 exports.normalizeEdgePop = normalizeEdgePop;
 exports.normalizeActivityId = normalizeActivityId;
+exports.sourceRegionFromEdgePop = sourceRegionFromEdgePop;
 exports.metadataFromHeaders = metadataFromHeaders;
 exports.serviceFromPath = serviceFromPath;
 exports.activityFlow = activityFlow;
 exports.presenceBucket = presenceBucket;
 exports.presenceKeys = presenceKeys;
+const index_js_1 = require("./index.js");
 exports.DEFAULT_PRESENCE_BUCKET_MS = 30000;
+/** @deprecated Unused by any Oxy repo; `presenceKeys` already encodes the window. Removal is planned for the next major. */
 exports.DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60000;
 function firstHeaderValue(value) {
     if (typeof value === 'string')
@@ -25,23 +28,43 @@ 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.
+ */
+function sourceRegionFromEdgePop(edgePop) {
+    return edgePop ? `edge-${edgePop}` : undefined;
+}
 function metadataFromHeaders(headers) {
-    const forwardedPop = normalizeEdgePop(headers['x-oxy-edge-region']);
+    const forwardedPop = normalizeEdgePop(headers[index_js_1.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[index_js_1.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.
+ */
 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.
+ */
 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.
+ */
 function presenceBucket(observedAt, bucketMs = exports.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/cjs/socket.js

@@ -49,9 +49,7 @@ function observeTrafficSocket(socket, collector, service, region, options = {})
         const edgePop = (0, server_js_1.metadataFromHeaders)(socket.handshake.headers).edgePop;
         const peerRegion = peerService
             ? (0, collector_js_1.normalizeInfrastructureRegion)(peer?.region)
-            : edgePop
-                ? `edge-${edgePop}`
-                : undefined;
+            : (0, server_js_1.sourceRegionFromEdgePop)(edgePop);
         collector.record({
             region,
             service,
@@ -90,9 +88,7 @@ function observeTrafficWebSocket(socket, collector, service, region, options = {
         const edgePop = (0, server_js_1.metadataFromHeaders)(options.headers ?? {}).edgePop;
         const peerRegion = peerService
             ? (0, collector_js_1.normalizeInfrastructureRegion)(peer?.region)
-            : edgePop
-                ? `edge-${edgePop}`
-                : undefined;
+            : (0, server_js_1.sourceRegionFromEdgePop)(edgePop);
         collector.record({
             service,
             region,

package/dist/esm/browser.js

@@ -26,6 +26,12 @@ function eligibleLocation(location) {
         location.hostname !== '127.0.0.1' &&
         location.hostname !== '[::1]');
 }
+/**
+ * @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 = {}) {
     let activityId = null;
     let activityIdCreatedAt = 0;
@@ -118,4 +124,9 @@ const defaultBrowserTelemetry = createBrowserTelemetry();
 export const getBrowserActivityIdHeader = () => defaultBrowserTelemetry.getActivityIdHeader();
 export const getBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.getEdgeRegionHeader();
 export const peekBrowserEdgeRegionHeader = () => 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 = () => defaultBrowserTelemetry.getHeaders();

package/dist/esm/collector.js

@@ -1,4 +1,5 @@
-import { metadataFromHeaders } from './server.js';
+import { OXY_REGION_HEADER, OXY_SOURCE_REGION_HEADER, } from './index.js';
+import { metadataFromHeaders, sourceRegionFromEdgePop } from './server.js';
 const TYPES = {
     auth: 'identity',
     session: 'identity',
@@ -39,6 +40,35 @@ export function trafficType(path) {
         parts.shift();
     return TYPES[parts[0] ?? ''] ?? 'platform';
 }
+/**
+ * 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 const UNOBSERVED_PATHS = [
+    {
+        directions: 'inbound',
+        matches: (path) => /^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|infra-status)(?:\/|$)/.test(path),
+    },
+    {
+        directions: 'inbound',
+        matches: (path) => /^\/(?:api\/)?platform-infrastructure(?:\/|$)/.test(path),
+    },
+    { directions: 'outbound', matches: (path) => path === '/platform-infrastructure' },
+    { directions: 'both', matches: (path) => path.startsWith('/internal/activity') },
+    { directions: 'both', matches: (path) => path.startsWith('/auth/service-token') },
+    { directions: 'inbound', matches: (path) => path.startsWith('/cdn-cgi/') },
+];
+/**
+ * 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 function isObservedPath(path, direction) {
+    return !UNOBSERVED_PATHS.some((entry) => (entry.directions === 'both' || entry.directions === direction) && entry.matches(path));
+}
 export function createTrafficCollector(publish, now = Date.now) {
     const pending = new Map();
     let flushing = null;
@@ -79,13 +109,10 @@ export function createTrafficCollector(publish, now = Date.now) {
 }
 export function trafficMiddleware(collector, service, region) {
     return (request, response, next) => {
-        response.setHeader?.('X-Oxy-Region', region);
+        response.setHeader?.(OXY_REGION_HEADER, 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/')) {
+        if (!isObservedPath(path, 'inbound')) {
             next();
             return;
         }
@@ -99,12 +126,10 @@ export function trafficMiddleware(collector, service, region) {
                 .replace(/[^a-z0-9-]/g, '-')
                 .slice(0, 40);
             const internal = Boolean(name);
-            const forwardedRegion = request.headers['x-oxy-source-region'];
+            const forwardedRegion = request.headers[OXY_SOURCE_REGION_HEADER.toLowerCase()];
             const peerRegion = internal
                 ? normalizeInfrastructureRegion(forwardedRegion)
-                : edgePop
-                    ? `edge-${edgePop}`
-                    : undefined;
+                : sourceRegionFromEdgePop(edgePop);
             return {
                 region,
                 service,
@@ -148,9 +173,7 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
     return Object.assign(async (input, init) => {
         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')
+        if (!isObservedPath(url.pathname, 'outbound'))
             return fetcher(input, init);
         const peer = resolveEndpoint(url);
         const flow = {
@@ -166,7 +189,7 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
         };
         const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
         if (peer)
-            headers.set('X-Oxy-Source-Region', region);
+            headers.set(OXY_SOURCE_REGION_HEADER, region);
         let response;
         try {
             response = await fetcher(input, { ...init, headers });
@@ -176,7 +199,7 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
             throw error;
         }
         const targetRegion = peer
-            ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined)
+            ? normalizeInfrastructureRegion(response.headers.get(OXY_REGION_HEADER) ?? undefined)
             : undefined;
         collector.record({ ...flow, targetRegion });
         collector.record({
@@ -194,11 +217,12 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
 // to be an internal service. Region is infrastructure metadata, never IP geo.
 const OXY_API_SERVICES = {
     'api.oxy.so': 'oxy-api',
-    'api.website.oxy.so': 'website',
     'website-api.oxy.so': 'website',
     'api.mention.earth': 'mention',
     'api.mercaria.co': 'mercaria',
+    // Old Alia app builds still call it; goes when api.alia.onl is retired (Gemies ADR 0034).
     'api.alia.onl': 'alia',
+    'api.gemies.ai': 'gemies',
     'kaana.ai': 'kaana',
     'api.homiio.com': 'homiio',
     'api.syra.fm': 'syra',

package/dist/esm/index.js

@@ -1,2 +1,23 @@
+/** Request header a browser sends: the ephemeral anonymous activity ID. */
 export const OXY_ACTIVITY_ID_HEADER = 'X-Oxy-Activity-Id';
+/** Request header a browser sends: the three-letter Cloudflare PoP code. */
 export const OXY_EDGE_REGION_HEADER = 'X-Oxy-Edge-Region';
+/** Response header a reporting service sets: the region that processed the request. */
+export const OXY_REGION_HEADER = 'X-Oxy-Region';
+/** Request header one Oxy service sends another: the caller's infrastructure region. */
+export 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 const OXY_TELEMETRY_REQUEST_HEADERS = Object.freeze([
+    OXY_ACTIVITY_ID_HEADER,
+    OXY_EDGE_REGION_HEADER,
+]);
+/**
+ * Response headers a browser client may need to read
+ * (`Access-Control-Expose-Headers`).
+ */
+export const OXY_TELEMETRY_EXPOSED_HEADERS = Object.freeze([OXY_REGION_HEADER]);

package/dist/esm/metrics.js

@@ -97,6 +97,15 @@ function seriesKey(metric, labels) {
 function defaultWrite(line) {
     globalThis.process?.stdout?.write?.(`${line}\n`);
 }
+/** Set by ECS on every task: the one reliable signal that `awslogs` is capturing stdout. */
+const ECS_METADATA_ENV = 'ECS_CONTAINER_METADATA_URI_V4';
+/**
+ * `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 function createEmfPublisherIfDeployed(options, env = globalThis.process?.env ?? {}) {
+    return env[ECS_METADATA_ENV] ? createEmfPublisher(options) : null;
+}
 export function createEmfPublisher(options) {
     const flushIntervalMs = options.flushIntervalMs ?? 60000;
     const maxSeries = options.maxSeries ?? 2000;