Initial Commit

openspec/archive/2026-04-19-enterprise-opentelemetry/proposal.md

@@ -0,0 +1,74 @@
+# OpenSpec Change: enterprise-opentelemetry
+
+- **Change ID**: enterprise-opentelemetry
+- **Package**: `@suaveplan/opentelemetry`
+- **Category**: universal
+- **Target path**: `universal/platform/opentelemetry`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/opentelemetry.md`
+
+## Summary
+
+Zero-dependency, spec-compliant implementation of the OpenTelemetry tracing + metrics data model. Suaveplan's own tracer, meter, context, propagation, and exporter primitives — used as the default tracer when no third-party OTel SDK is wired. Includes a `SuaveplanError` interceptor that auto-records errors as span events.
+
+## Current-state audit (genesis)
+
+Package does not exist yet — fresh build. Genesis currently uses the upstream `@opentelemetry/api` directly; this package lands the vendor-neutral runtime substrate that makes `@opentelemetry/api` a no-op until an exporter is registered.
+
+## Dependencies
+
+- Workspace: `@suaveplan/error`, `@suaveplan/types`
+- External (via catalog): `@opentelemetry/api` → `catalog:observability`; `zod` → `catalog:forms`; `tslib` → `catalog:build`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+
+### Core – context + propagation
+
+- `Context`, `ContextManager`, `getSpanFromContext`, `setSpanInContext`
+- `TextMapCarrier`, `TextMapGetter`, `TextMapPropagator`, `TextMapSetter`, `defaultTextMapGetter`, `defaultTextMapSetter`
+
+### Core – tracer + span
+
+- `Tracer`, `TracerProvider`, `TracerProviderConfig`, `TracerProviderOptions`, `ITracer`, `ITracerProvider`
+- `Span`, `SpanConfig`, `WritableSpan`
+
+### Core – meter
+
+- `Meter`, `MeterProvider`, `Counter`, `Gauge`, `Histogram`
+- `ICounter`, `IGauge`, `IHistogram`, `IMeter`, `IMeterProvider`
+
+### Propagation
+
+- Baggage: `Baggage`, `BaggageEntry`, `W3CBaggagePropagator`, `getBaggageFromContext`, `parseBaggage`, `serializeBaggage`, `setBaggageInContext`
+- W3C Trace Context: `W3CTraceContextPropagator`, `getRemoteSpanContext`, `parseTraceparent`, `parseTraceState`, `serializeTraceparent`, `serializeTraceState`
+
+### Exporters
+
+- `ConsoleSpanExporter`, `ConsoleExporterOptions`, `InMemorySpanExporter`
+
+### Error bridge
+
+- `installSuaveplanErrorInterceptor`, `isSuaveplanErrorInterceptorInstalled`, `InstallSuaveplanErrorInterceptorOptions`, `UninstallSuaveplanErrorInterceptor`
+
+### Constants / utils
+
+- `BAGGAGE_HEADER`, `INVALID_SPAN_ID`, `INVALID_TRACE_ID`, `MAX_BAGGAGE_ENTRIES`, `MAX_SPAN_ATTRIBUTES`, `MAX_SPAN_EVENTS`, `MAX_SPAN_LINKS`, `SPAN_ID_HEX_LENGTH`, `TRACE_ID_HEX_LENGTH`, `TRACE_VERSION`, `TRACEPARENT_HEADER`, `TRACESTATE_HEADER`
+- `generateSpanId`, `generateTraceId`, `hrTimeMs`, `isValidSpanId`, `isValidTraceId`
+
+### Types
+
+`Attributes`, `AttributeValue`, `ExportResult`, `ExportResultCode`, `HistogramDataPoint`, `HistogramOptions`, `InstrumentationScope`, `MetricDataPoint`, `MetricOptions`, `MetricValueType`, `ReadableSpan`, `Resource`, `SpanContext`, `SpanEvent`, `SpanExporter`, `SpanKind`, `SpanLink`, `SpanOptions`, `SpanStatus`, `SpanStatusCode`, `TraceFlags`.
+
+## New genesis additions
+
+- Codes: `OTEL.INVALID_TRACE_ID`, `OTEL.INVALID_SPAN_ID`, `OTEL.EXPORT_FAILED`, `OTEL.LIMIT_EXCEEDED`.
+- Zod schemas for every constant-limit-bearing type.
+- Compatibility layer tests that verify `@opentelemetry/api` defers to the package's global tracer provider when set.
+- Property tests: `parseTraceparent ∘ serializeTraceparent` round-trip, valid sample-flag combinations preserved.
+
+## Impact
+
+- Adds one new package: `universal/platform/opentelemetry`
+- Adds one new spec capability: `opentelemetry`