pome-sh 0.6.6

package/node_modules/@pome-sh/shared-types/src/otel/legacy-shim.ts

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * otel/legacy-shim — legacy event → `OtelSpanEvent` translation (M1.2 / FDRS-481).
+ *
+ * The compatibility layer for the transition window: the CLI keeps uploading its
+ * current JSONL (no flag day), and OTel-aware downstream (M3 correlation, the
+ * native waterfall) reads `OtelSpanEvent`. This shim translates the three legacy
+ * variants — `TwinHttpEvent`, `LlmCallEvent`, `ToolUseEvent` — up into spans so
+ * legacy and new data share one path.
+ *
+ * Guarantees:
+ *   - **Lossless.** The ENTIRE original record is preserved verbatim as a JSON
+ *     string under `attributes["pome.legacy.record_json"]` — serialized from the
+ *     raw input BEFORE Zod strips any additive fields (review finding #3). The
+ *     mapped fields are ALSO written as canonical OTel attributes, from which
+ *     the typed projections are derived by the SAME projector the schema checks.
+ *   - **Deterministic.** No clock, no randomness. Same record (+ same `run_id`
+ *     option) → byte-identical span, every run.
+ *   - **OTel-correct status** (review findings #5/#9). HTTP client spans: 1xx–3xx
+ *     leave status UNSET; 4xx/5xx and transport errors are ERROR. (OTel does not
+ *     set OK on a merely-successful span.)
+ *
+ * IDs are namespaced `legacy:<source-id>` so a stored span always declares it
+ * originated from a pre-OTel record (the canonical schema accepts either real
+ * W3C ids or `legacy:` ids).
+ *
+ * Pinned convention: the shim targets `OTEL_GENAI_SCHEMA_VERSION` (see `./semconv`).
+ */
+
+import { z } from "zod";
+
+import {
+  llmCallEventSchema,
+  toolUseEventSchema,
+  twinHttpEventSchema,
+} from "../recorder-events.js";
+import { msToNanos, nanosToIso } from "./nano.js";
+import {
+  projectAttributes,
+  type OtelAttributeBag,
+  type OtelAttributeValue,
+} from "./project.js";
+import {
+  ERROR_TYPE,
+  GEN_AI_OPERATION_NAME,
+  GEN_AI_REQUEST_MODEL,
+  GEN_AI_TOOL_NAME,
+  GEN_AI_USAGE_INPUT_TOKENS,
+  GEN_AI_USAGE_OUTPUT_TOKENS,
+  HTTP_REQUEST_METHOD,
+  HTTP_RESPONSE_STATUS_CODE,
+  OTEL_GENAI_SCHEMA_VERSION,
+  SERVER_ADDRESS,
+  SERVER_PORT,
+  URL_FULL,
+  URL_PATH,
+} from "./semconv.js";
+import { otelSpanEventSchema, type OtelSpanEvent } from "./span-event.js";
+
+// The shim targets this pinned GenAI convention version (from M1.1). This
+// re-export makes the pin explicit and testable.
+export const LEGACY_SHIM_SEMCONV_VERSION = OTEL_GENAI_SCHEMA_VERSION;
+
+// The documented namespace for legacy provenance. `record_json` is the lossless
+// source of truth; `kind` records the originating legacy variant.
+export const LEGACY_ATTR_NAMESPACE = "pome.legacy" as const;
+export const LEGACY_ID_PREFIX = "legacy:" as const;
+const ATTR_LEGACY_KIND = `${LEGACY_ATTR_NAMESPACE}.kind`;
+const ATTR_LEGACY_RECORD_JSON = `${LEGACY_ATTR_NAMESPACE}.record_json`;
+
+// The legacy variants this shim accepts. Discriminated on `kind`.
+export const shimmableLegacyEventSchema = z.discriminatedUnion("kind", [
+  twinHttpEventSchema,
+  llmCallEventSchema,
+  toolUseEventSchema,
+]);
+export type ShimmableLegacyEvent = z.infer<typeof shimmableLegacyEventSchema>;
+
+export interface LegacyShimOptions {
+  // The legacy RUN this record belongs to — used to group rows into one trace.
+  // Legacy JSONL is uploaded per run, so the caller knows it. REQUIRED for
+  // `LlmCallEvent` / `ToolUseEvent` (no internal run context); a `TwinHttpEvent`
+  // falls back to its own `run_id`. Stored as `legacy:<run_id>`.
+  run_id?: string;
+}
+
+// `legacy:`-namespace a non-OTel source id. Idempotent if already namespaced.
+function legacyId(sourceId: string): string {
+  return sourceId.startsWith(LEGACY_ID_PREFIX) ? sourceId : `${LEGACY_ID_PREFIX}${sourceId}`;
+}
+
+// Resolve the legacy run id used as the trace grouping key.
+function resolveRunId(options: LegacyShimOptions, record: ShimmableLegacyEvent): string {
+  if (options.run_id !== undefined) {
+    return options.run_id;
+  }
+  if (record.kind === "TwinHttpEvent") {
+    return record.run_id;
+  }
+  // No run context — LLM/tool rows carry none internally. Refusing here keeps
+  // related rows from each landing in their own orphan trace.
+  throw new Error(
+    `legacy-shim: ${record.kind} requires options.run_id for trace context`,
+  );
+}
+
+// Drop null/undefined entries so the bag stays a valid attribute record (the
+// attribute schema has no null member — an absent attribute is omitted).
+function buildBag(
+  entries: Record<string, OtelAttributeValue | null | undefined>,
+): OtelAttributeBag {
+  const bag: OtelAttributeBag = {};
+  for (const [key, value] of Object.entries(entries)) {
+    if (value !== null && value !== undefined) bag[key] = value;
+  }
+  return bag;
+}
+
+// OTel HTTP client span status: success (incl. redirects) stays UNSET; 4xx/5xx
+// and transport errors are ERROR (review #9). Returns the status + the
+// low-cardinality `error.type` token to stamp on the bag.
+function httpStatus(
+  status: number,
+  error: string | null,
+): { code: "UNSET" | "ERROR"; errorType: string | null } {
+  if (error !== null) return { code: "ERROR", errorType: "network_error" };
+  if (status >= 400) return { code: "ERROR", errorType: String(status) };
+  return { code: "UNSET", errorType: null };
+}
+
+/**
+ * Translate a single legacy `TwinHttpEvent` / `LlmCallEvent` / `ToolUseEvent`
+ * into a validated `OtelSpanEvent`.
+ *
+ * Throws a typed `ZodError` if `rawRecord` is not one of those three shapes,
+ * or a plain `Error` if an LLM/tool record is missing the required `run_id`.
+ */
+export function shimLegacyEventToSpan(
+  rawRecord: unknown,
+  options: LegacyShimOptions = {},
+): OtelSpanEvent {
+  const record = shimmableLegacyEventSchema.parse(rawRecord);
+
+  const startMs = Date.parse(record.ts);
+  const startNano = msToNanos(startMs);
+  const traceId = legacyId(resolveRunId(options, record));
+  const spanId = legacyId(record.event_id);
+  const parentSpanId = record.parent_id !== null ? legacyId(record.parent_id) : null;
+
+  // Lossless: serialize the RAW input (not the Zod-stripped record) so additive
+  // legacy fields survive round-trip.
+  const legacyNamespace = {
+    [ATTR_LEGACY_KIND]: record.kind,
+    [ATTR_LEGACY_RECORD_JSON]: JSON.stringify(rawRecord),
+  };
+
+  let name: string;
+  let spanKind: OtelSpanEvent["span_kind"];
+  let endNano: string | null;
+  let statusCode: OtelSpanEvent["status_code"];
+  let statusMessage: string | null;
+  let semanticAttrs: OtelAttributeBag;
+
+  if (record.kind === "TwinHttpEvent") {
+    const status = httpStatus(record.status, record.error);
+    // Low-cardinality span name: HTTP method only (the concrete path is a high-
+    // cardinality URL, not a route template) — review #4.
+    name = record.method;
+    spanKind = "CLIENT";
+    endNano = msToNanos(startMs + record.latency_ms);
+    statusCode = status.code;
+    statusMessage = record.error;
+    semanticAttrs = buildBag({
+      [HTTP_REQUEST_METHOD]: record.method,
+      [HTTP_RESPONSE_STATUS_CODE]: record.status,
+      [URL_PATH]: record.path,
+      [ERROR_TYPE]: status.errorType,
+    });
+  } else if (record.kind === "LlmCallEvent") {
+    // Asymmetry vs TwinHttpEvent (intentional, M1): a legacy LlmCallEvent has no
+    // transport-error field, so only an HTTP >=400 status drives ERROR here —
+    // a connection-level failure with a null status stays UNSET. M3 unifies on
+    // real OTel span status; until then LLM rows may under-report errors vs HTTP.
+    const errored = record.status !== null && record.status >= 400;
+    name = record.model !== null ? `chat ${record.model}` : "chat";
+    spanKind = "CLIENT";
+    endNano = msToNanos(startMs + record.latency_ms);
+    statusCode = errored ? "ERROR" : "UNSET";
+    statusMessage = null;
+    semanticAttrs = buildBag({
+      [GEN_AI_OPERATION_NAME]: "chat",
+      [GEN_AI_REQUEST_MODEL]: record.model,
+      [GEN_AI_USAGE_INPUT_TOKENS]: record.prompt_tokens,
+      [GEN_AI_USAGE_OUTPUT_TOKENS]: record.completion_tokens,
+      [HTTP_REQUEST_METHOD]: record.method,
+      [HTTP_RESPONSE_STATUS_CODE]: record.status,
+      [URL_FULL]: record.url,
+      [SERVER_ADDRESS]: record.host,
+      [SERVER_PORT]: record.port,
+      [ERROR_TYPE]: errored ? String(record.status) : null,
+    });
+  } else {
+    // ToolUseEvent
+    name = `execute_tool ${record.tool_name}`;
+    spanKind = "INTERNAL";
+    endNano = null;
+    statusCode = "UNSET";
+    statusMessage = null;
+    semanticAttrs = buildBag({
+      [GEN_AI_OPERATION_NAME]: "execute_tool",
+      [GEN_AI_TOOL_NAME]: record.tool_name,
+    });
+  }
+
+  const attributes: OtelAttributeBag = { ...semanticAttrs, ...legacyNamespace };
+
+  const candidate = {
+    ts: nanosToIso(startNano),
+    event_id: spanId,
+    parent_id: parentSpanId,
+    kind: "OtelSpanEvent" as const,
+    trace_id: traceId,
+    span_id: spanId,
+    parent_span_id: parentSpanId,
+    name,
+    span_kind: spanKind,
+    start_time_unix_nano: startNano,
+    end_time_unix_nano: endNano,
+    status_code: statusCode,
+    status_message: statusMessage,
+    ...projectAttributes(attributes),
+    attributes,
+  };
+
+  // Re-validate so the shim's output is provably a canonical `OtelSpanEvent`.
+  return otelSpanEventSchema.parse(candidate);
+}

package/node_modules/@pome-sh/shared-types/src/otel/map-span.ts

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * otel/map-span — pure OTel span → `OtelSpanEvent` mapping (M1.1 / FDRS-480).
+ *
+ * Deterministic: same input → byte-identical event, every run. Has no clock,
+ * no randomness; `ts` is derived from the span's start time.
+ *
+ * Input is a NORMALIZED span: real W3C trace context (lowercase-hex ids) and a
+ * flat `attributes` `Record<string, value>`. Decoding raw OTLP/JSON `AnyValue`
+ * (`{ stringValue }`, kvlist, bytes) and the `[{ key, value }]` attribute array
+ * into this flat record is M2's job (the `@opentelemetry/otlp-transformer`
+ * dependency) — keeping M1.1 free of an OTLP decoder keeps the schema
+ * self-testable.
+ *
+ * Round-trip example:
+ *
+ *   mapOtelSpanToEvent({
+ *     trace_id: "4bf92f3577b34da6a3ce929d0e0e4736",
+ *     span_id: "00f067aa0ba902b7",
+ *     name: "chat google/gemini-2.5-flash",
+ *     start_time_unix_nano: "1700000000000000000",
+ *     attributes: {
+ *       "gen_ai.provider.name": "google",
+ *       "gen_ai.request.model": "gemini-2.5-flash",
+ *       "gen_ai.usage.input_tokens": 42,
+ *     },
+ *   })
+ *   // → { ts: "2023-11-14T22:13:20.000Z", event_id: "00f067aa0ba902b7", … }
+ */
+
+import { z } from "zod";
+
+import { nanosToIso } from "./nano.js";
+import { otelAttributeValueSchema, projectAttributes } from "./project.js";
+import {
+  OTEL_SPAN_KINDS,
+  OTEL_STATUS_CODES,
+  otelSpanEventSchema,
+  otelSpanKindSchema,
+  otelStatusCodeSchema,
+  unixNanoSchema,
+  w3cSpanIdSchema,
+  w3cTraceIdSchema,
+  type OtelSpanEvent,
+  type OtelSpanKind,
+  type OtelStatusCode,
+} from "./span-event.js";
+
+// Normalized OTLP span input. IDs are strict W3C trace context (real OTel
+// always emits hex). `kind` / `status.code` accept either the OTLP integer
+// (0–5 / 0–2) or the name; everything else is already decoded.
+export const otelSpanInputSchema = z.object({
+  trace_id: w3cTraceIdSchema,
+  span_id: w3cSpanIdSchema,
+  parent_span_id: w3cSpanIdSchema.nullable().optional(),
+  name: z.string().min(1),
+  kind: z.union([otelSpanKindSchema, z.number().int().min(0).max(5)]).optional(),
+  start_time_unix_nano: unixNanoSchema,
+  end_time_unix_nano: unixNanoSchema.nullable().optional(),
+  status: z
+    .object({
+      code: z.union([otelStatusCodeSchema, z.number().int().min(0).max(2)]).optional(),
+      message: z.string().nullable().optional(),
+    })
+    .optional(),
+  attributes: z.record(z.string(), otelAttributeValueSchema).default({}),
+});
+export type OtelSpanInput = z.infer<typeof otelSpanInputSchema>;
+
+function normalizeSpanKind(kind: OtelSpanInput["kind"]): OtelSpanKind {
+  if (kind === undefined) {
+    // OTel SDKs default an unset kind to INTERNAL.
+    return "INTERNAL";
+  }
+  if (typeof kind === "number") {
+    // Bounded 0–5 by `otelSpanInputSchema`; `!` avoids an unreachable branch.
+    return OTEL_SPAN_KINDS[kind]!;
+  }
+  return kind;
+}
+
+function normalizeStatusCode(code: number | OtelStatusCode | undefined): OtelStatusCode {
+  if (code === undefined) {
+    return "UNSET";
+  }
+  if (typeof code === "number") {
+    // Bounded 0–2 by `otelSpanInputSchema`; `!` avoids an unreachable branch.
+    return OTEL_STATUS_CODES[code]!;
+  }
+  return code;
+}
+
+/**
+ * Map a normalized OTLP span onto a validated `OtelSpanEvent`.
+ *
+ * Throws a `ZodError` (typed; names the offending field) when the input is
+ * malformed — a non-hex `trace_id`, an out-of-range unix-nano, a reversed span
+ * (end < start), a non-finite attribute value, etc.
+ */
+export function mapOtelSpanToEvent(rawSpan: unknown): OtelSpanEvent {
+  const span = otelSpanInputSchema.parse(rawSpan);
+  const attributes = span.attributes;
+  const parentSpanId = span.parent_span_id ?? null;
+
+  const candidate = {
+    ts: nanosToIso(span.start_time_unix_nano),
+    // The span id IS the canonical row id for an OTel event; the base
+    // parent-chain mirrors span parentage so downstream union readers and M3
+    // correlation agree.
+    event_id: span.span_id,
+    parent_id: parentSpanId,
+    kind: "OtelSpanEvent" as const,
+
+    trace_id: span.trace_id,
+    span_id: span.span_id,
+    parent_span_id: parentSpanId,
+
+    name: span.name,
+    span_kind: normalizeSpanKind(span.kind),
+    start_time_unix_nano: span.start_time_unix_nano,
+    end_time_unix_nano: span.end_time_unix_nano ?? null,
+    status_code: normalizeStatusCode(span.status?.code),
+    status_message: span.status?.message ?? null,
+
+    // Verbatim bag plus its single-source projection. The schema re-derives the
+    // projection and rejects drift, so this is the only place it is computed.
+    ...projectAttributes(attributes),
+    attributes,
+  };
+
+  // Re-validate the assembled event so the canonical model is always schema-
+  // valid. This DOES fire for bad input the input schema let through (e.g. a
+  // reversed span), surfacing a typed ZodError instead of a silent bad row.
+  return otelSpanEventSchema.parse(candidate);
+}

package/node_modules/@pome-sh/shared-types/src/otel/nano.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * otel/nano — uint64 decimal-string arithmetic + nanosecond↔ISO conversion
+ * (M1.1 / FDRS-480).
+ *
+ * OTLP encodes `*_unix_nano` timestamps as uint64 decimal STRINGS because the
+ * values exceed Number.MAX_SAFE_INTEGER. These helpers validate and compare
+ * them WITHOUT `BigInt` — the dashboard compiles this source directly under a
+ * pre-ES2020 target where `BigInt` literals fail to typecheck (review-era
+ * portability fix). Everything here is pure and deterministic.
+ */
+
+// 2^64 - 1. A unix-nano timestamp must fit in a uint64; a longer/larger decimal
+// string is rejected so it can never reach `nanosToIso` and throw a RangeError
+// (review finding #4).
+export const UINT64_MAX = "18446744073709551615";
+
+// Strip leading zeros, keeping a single "0" for an all-zero string. The
+// `(?=\d)` lookahead guarantees at least one digit remains, so for any digit
+// string (callers validate via the `^\d+$` test first) the result is non-empty.
+// Lets us compare normalized decimals by (length, then lexicographic).
+function normalizeDigits(value: string): string {
+  return value.replace(/^0+(?=\d)/, "");
+}
+
+/** True iff `value` is a non-negative decimal integer string within uint64. */
+export function isUint64(value: string): boolean {
+  if (!/^\d+$/.test(value)) return false;
+  const normalized = normalizeDigits(value);
+  if (normalized.length !== UINT64_MAX.length) {
+    return normalized.length < UINT64_MAX.length;
+  }
+  return normalized <= UINT64_MAX;
+}
+
+/**
+ * Compare two uint64 decimal strings. Returns <0 if a<b, 0 if equal, >0 if a>b.
+ * Assumes both are valid digit strings (callers validate via `isUint64` first).
+ */
+export function compareUint64(a: string, b: string): number {
+  const na = normalizeDigits(a);
+  const nb = normalizeDigits(b);
+  if (na.length !== nb.length) return na.length - nb.length;
+  if (na === nb) return 0;
+  return na < nb ? -1 : 1;
+}
+
+// Unix-milliseconds → uint64 unix-nanoseconds decimal string. Legacy timestamps
+// are millisecond-precision, so this is exact: append six zeros. Deterministic.
+export function msToNanos(millis: number): string {
+  return `${millis}000000`;
+}
+
+/**
+ * uint64 nanoseconds → ISO-8601 (UTC). Floors to milliseconds by dropping the
+ * last 6 decimal digits of the (uint64-validated) integer string. The resulting
+ * ms value is within Date's safe range for any valid uint64, so this never
+ * throws for input that passed `isUint64`. String-slicing avoids `BigInt`.
+ */
+export function nanosToIso(unixNano: string): string {
+  const millis = Number(unixNano.slice(0, -6) || "0");
+  return new Date(millis).toISOString();
+}

package/node_modules/@pome-sh/shared-types/src/otel/project.ts

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * otel/project — the single attribute→projection function (M1.1 / FDRS-480).
+ *
+ * The typed `gen_ai_*` / `http_*` / `url_*` / `server_*` / `error_type` fields
+ * on an `OtelSpanEvent` are PROJECTIONS of the verbatim `attributes` bag, never
+ * an independent source of truth. This module is the ONE place that derivation
+ * lives, so:
+ *   - the span mapper (`map-span.ts`) builds projections from `attributes`,
+ *   - the legacy shim (`legacy-shim.ts`) builds them the same way, and
+ *   - the schema (`span-event.ts`) re-derives them in a `superRefine` and
+ *     rejects any event whose typed fields drift from `attributes`
+ *     (review finding #4 — projection drift; finding #7 — centralize).
+ *
+ * Pure and deterministic. Reads only the pinned attribute names from `semconv`.
+ */
+
+import { z } from "zod";
+
+import {
+  ERROR_TYPE,
+  GEN_AI_AGENT_ID,
+  GEN_AI_AGENT_NAME,
+  GEN_AI_OPERATION_NAME,
+  GEN_AI_PROVIDER_NAME,
+  GEN_AI_REQUEST_MODEL,
+  GEN_AI_SYSTEM_DEPRECATED,
+  GEN_AI_TOOL_NAME,
+  GEN_AI_USAGE_COMPLETION_TOKENS_LEGACY,
+  GEN_AI_USAGE_INPUT_TOKENS,
+  GEN_AI_USAGE_OUTPUT_TOKENS,
+  GEN_AI_USAGE_PROMPT_TOKENS_LEGACY,
+  HTTP_REQUEST_METHOD,
+  HTTP_RESPONSE_STATUS_CODE,
+  SERVER_ADDRESS,
+  SERVER_PORT,
+  URL_FULL,
+  URL_PATH,
+} from "./semconv.js";
+
+// A flattened OTLP attribute value. OTLP `AnyValue` decoding (kvlist/bytes/
+// nested) is M2's job; at the schema boundary an attribute is a primitive or a
+// homogeneous-ish array of primitives. Numbers must be FINITE — `Infinity`/`NaN`
+// are not representable in OTLP and would corrupt projections (review #4).
+const finiteNumber = z.number().finite();
+export const otelAttributeValueSchema = z.union([
+  z.string(),
+  finiteNumber,
+  z.boolean(),
+  z.array(z.union([z.string(), finiteNumber, z.boolean()])),
+]);
+export type OtelAttributeValue = z.infer<typeof otelAttributeValueSchema>;
+
+export type OtelAttributeBag = Record<string, OtelAttributeValue>;
+
+// The full set of projection field names, in on-disk order. The schema's
+// drift check iterates this so a new projection can never be added to the
+// schema without the projector also producing it.
+export const OTEL_PROJECTION_KEYS = [
+  "gen_ai_provider_name",
+  "gen_ai_operation_name",
+  "gen_ai_request_model",
+  "gen_ai_agent_name",
+  "gen_ai_agent_id",
+  "gen_ai_tool_name",
+  "gen_ai_usage_input_tokens",
+  "gen_ai_usage_output_tokens",
+  "http_request_method",
+  "http_response_status_code",
+  "url_full",
+  "url_path",
+  "server_address",
+  "server_port",
+  "error_type",
+] as const;
+
+export type OtelProjections = {
+  gen_ai_provider_name: string | null;
+  gen_ai_operation_name: string | null;
+  gen_ai_request_model: string | null;
+  gen_ai_agent_name: string | null;
+  gen_ai_agent_id: string | null;
+  gen_ai_tool_name: string | null;
+  gen_ai_usage_input_tokens: number | null;
+  gen_ai_usage_output_tokens: number | null;
+  http_request_method: string | null;
+  http_response_status_code: number | null;
+  url_full: string | null;
+  url_path: string | null;
+  server_address: string | null;
+  server_port: number | null;
+  error_type: string | null;
+};
+
+// present-and-string → the string, else null.
+function readString(attributes: OtelAttributeBag, key: string): string | null {
+  const value = attributes[key];
+  return typeof value === "string" ? value : null;
+}
+
+// present-and-finite-int → the number, else null. (Finiteness is already
+// enforced by the attribute schema; the guard keeps the projector total even
+// when called on a not-yet-validated bag.)
+function readInt(attributes: OtelAttributeBag, key: string): number | null {
+  const value = attributes[key];
+  return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+
+// present-and-int≥0 → the number, else null. Token counts and ports are
+// non-negative.
+function readUint(attributes: OtelAttributeBag, key: string): number | null {
+  const value = readInt(attributes, key);
+  return value !== null && value >= 0 ? value : null;
+}
+
+/**
+ * Derive the flat typed projections from a verbatim attribute bag. Canonical
+ * names win; deprecated/pre-1.27 aliases are accepted as fallbacks.
+ */
+export function projectAttributes(attributes: OtelAttributeBag): OtelProjections {
+  return {
+    gen_ai_provider_name:
+      readString(attributes, GEN_AI_PROVIDER_NAME) ??
+      readString(attributes, GEN_AI_SYSTEM_DEPRECATED),
+    gen_ai_operation_name: readString(attributes, GEN_AI_OPERATION_NAME),
+    gen_ai_request_model: readString(attributes, GEN_AI_REQUEST_MODEL),
+    gen_ai_agent_name: readString(attributes, GEN_AI_AGENT_NAME),
+    gen_ai_agent_id: readString(attributes, GEN_AI_AGENT_ID),
+    gen_ai_tool_name: readString(attributes, GEN_AI_TOOL_NAME),
+    gen_ai_usage_input_tokens:
+      readUint(attributes, GEN_AI_USAGE_INPUT_TOKENS) ??
+      readUint(attributes, GEN_AI_USAGE_PROMPT_TOKENS_LEGACY),
+    gen_ai_usage_output_tokens:
+      readUint(attributes, GEN_AI_USAGE_OUTPUT_TOKENS) ??
+      readUint(attributes, GEN_AI_USAGE_COMPLETION_TOKENS_LEGACY),
+    http_request_method: readString(attributes, HTTP_REQUEST_METHOD),
+    // HTTP status codes are non-negative (100–599); `readUint` drops a bogus
+    // negative value rather than projecting it as a valid code.
+    http_response_status_code: readUint(attributes, HTTP_RESPONSE_STATUS_CODE),
+    url_full: readString(attributes, URL_FULL),
+    url_path: readString(attributes, URL_PATH),
+    server_address: readString(attributes, SERVER_ADDRESS),
+    server_port: readUint(attributes, SERVER_PORT),
+    error_type: readString(attributes, ERROR_TYPE),
+  };
+}

package/node_modules/@pome-sh/shared-types/src/otel/semconv.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * otel/semconv — pinned OpenTelemetry semantic-convention surface (M1.1 / FDRS-480).
+ *
+ * The ONE place an upstream spec change is absorbed. Every attribute name the
+ * span mapper / shim reads is a constant here; the convention versions are
+ * pinned below. When the OTel conventions move, bump the relevant version and
+ * edit the affected constant here — `map-span.ts`, `project.ts`, and the schema
+ * never hard-code an attribute string, so the blast radius is this file.
+ *
+ * Two separate pins, because the GenAI and core/HTTP conventions version
+ * independently (review finding #5 — a single "1.30.0" mislabelled a mixed
+ * surface):
+ *   - `OTEL_CORE_SEMCONV_VERSION` — the stable core conventions (HTTP client
+ *     spans, url.*, server.*, error.type) we project. Pinned to the v1.41.1
+ *     core release.
+ *   - `OTEL_GENAI_SCHEMA_VERSION` — the (still-experimental) GenAI conventions
+ *     (`gen_ai.*`). Pinned to the GenAI schema 1.42.0, which introduces
+ *     `gen_ai.provider.name` and deprecates `gen_ai.system`.
+ *
+ * Provenance for the pins:
+ *   - core:  https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.41.1
+ *   - genai: https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai
+ *   - http:  https://opentelemetry.io/docs/specs/semconv/http/http-spans/
+ *
+ * This module is the canonical home of the pinned OTel convention surface;
+ * pome-cloud consumes it as part of `@pome-sh/shared-types` (ownership
+ * boundary settled at FDRS-653 — see `./index.ts`).
+ */
+
+// Pinned core (HTTP / url / server / error) convention version.
+export const OTEL_CORE_SEMCONV_VERSION = "1.41.1" as const;
+export type OtelCoreSemconvVersion = typeof OTEL_CORE_SEMCONV_VERSION;
+
+// Pinned GenAI convention/schema version. The GenAI surface is experimental and
+// versions ahead of core; `gen_ai.provider.name` is canonical at this version.
+export const OTEL_GENAI_SCHEMA_VERSION = "1.42.0" as const;
+export type OtelGenaiSchemaVersion = typeof OTEL_GENAI_SCHEMA_VERSION;
+
+// The GenAI schema URL emitters stamp on their resource/scope. Recorded so M2's
+// raw-OTLP ingestion can assert the producer's declared schema against our pin.
+export const OTEL_GENAI_SCHEMA_URL =
+  "https://opentelemetry.io/schemas/1.42.0" as const;
+
+// ── GenAI semantic conventions ───────────────────────────────────────────────
+// Emitted by Traceloop/OpenLLMetry, the Vercel AI SDK, Pydantic Logfire, and
+// Pome's own runtimes.
+
+// Canonical provider attribute at the pinned GenAI version (replaces
+// `gen_ai.system`, which is accepted as a deprecated ingestion alias below).
+export const GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
+// Deprecated alias for the provider. Still emitted by Traceloop and older AI-SDK
+// builds in the wild, so the projector accepts it and normalizes onto
+// `gen_ai_provider_name`. Remove when the pinned version drops the alias.
+export const GEN_AI_SYSTEM_DEPRECATED = "gen_ai.system";
+
+export const GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+export const GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+export const GEN_AI_AGENT_NAME = "gen_ai.agent.name";
+export const GEN_AI_AGENT_ID = "gen_ai.agent.id";
+export const GEN_AI_TOOL_NAME = "gen_ai.tool.name";
+export const GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
+export const GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+
+// Pre-1.27 token attribute names. Still emitted by older Traceloop/OpenLLMetry
+// builds, so the projector accepts them as a fallback and normalizes onto the
+// canonical `input_tokens` / `output_tokens` fields.
+export const GEN_AI_USAGE_PROMPT_TOKENS_LEGACY = "gen_ai.usage.prompt_tokens";
+export const GEN_AI_USAGE_COMPLETION_TOKENS_LEGACY = "gen_ai.usage.completion_tokens";
+
+// ── HTTP / core semantic conventions ─────────────────────────────────────────
+// External-API (twin-relevant) spans. Stable HTTP client conventions at the
+// pinned core version (`http.request.method`, not the deprecated `http.method`).
+export const HTTP_REQUEST_METHOD = "http.request.method";
+export const HTTP_RESPONSE_STATUS_CODE = "http.response.status_code";
+export const URL_FULL = "url.full";
+// `url.path` is the low-cardinality path component; safe to project even when
+// `url.full` carries query params we would not want in a span name.
+export const URL_PATH = "url.path";
+export const SERVER_ADDRESS = "server.address";
+export const SERVER_PORT = "server.port";
+// `error.type` is set on failed spans (status ERROR). For HTTP it is typically
+// the status-code class or an exception/connection-error identifier.
+export const ERROR_TYPE = "error.type";