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`

openspec/archive/2026-04-19-enterprise-opentelemetry/specs/opentelemetry/spec.md

@@ -0,0 +1,41 @@
+# Capability Spec: opentelemetry
+
+**Package**: `@suaveplan/opentelemetry`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### OT-01 — Identifier generation
+
+`generateTraceId()` MUST return a 32-character lowercase hex string (128 bits). `generateSpanId()` MUST return a 16-character lowercase hex string (64 bits). Both MUST be cryptographically random and MUST NOT produce the all-zero IDs defined in `INVALID_TRACE_ID` / `INVALID_SPAN_ID`.
+
+### OT-02 — W3C traceparent
+
+`serializeTraceparent({ version, traceId, spanId, flags })` MUST emit `<version>-<traceId>-<spanId>-<flags>` with `TRACE_VERSION` as version and lowercase hex flags. `parseTraceparent(str)` MUST round-trip cleanly; invalid input MUST throw `OTEL.INVALID_TRACE_ID` or `OTEL.INVALID_SPAN_ID`.
+
+### OT-03 — Baggage
+
+`W3CBaggagePropagator` MUST inject a `baggage: …` header comma-separated list of `key=value` pairs. `parseBaggage(header)` MUST tolerate percent-encoding and strip entries beyond `MAX_BAGGAGE_ENTRIES` (8192 by spec).
+
+### OT-04 — Span limits
+
+A span MUST enforce `MAX_SPAN_ATTRIBUTES`, `MAX_SPAN_EVENTS`, `MAX_SPAN_LINKS`. Exceeding any MUST emit `OTEL.LIMIT_EXCEEDED` (dropped attribute counter) and silently drop further entries.
+
+### OT-05 — Meter contract
+
+`Counter.add(value, attrs?)`, `Histogram.record(value, attrs?)`, `Gauge.set(value, attrs?)` MUST accept numeric values; negative values on `Counter` MUST be rejected per spec.
+
+### OT-06 — Error bridge
+
+`installSuaveplanErrorInterceptor()` MUST subscribe to the `@suaveplan/error` global interceptor and, for every error thrown inside an active span, add a span event `{ name: 'exception', attributes: { 'exception.type', 'exception.message', 'exception.stacktrace', 'exception.code' } }` and set `SpanStatus.ERROR`.
+
+### OT-07 — Exporters
+
+`ConsoleSpanExporter.export(spans)` MUST emit one line per span to the configured logger. `InMemorySpanExporter.export(spans)` MUST append spans to an array available via `getFinishedSpans()` for tests. Both MUST return `ExportResult { code: ExportResultCode.SUCCESS }` on success.
+
+### OT-08 — `@opentelemetry/api` compatibility
+
+Importing the package MUST register its `TracerProvider` and `MeterProvider` as the globals through `@opentelemetry/api` when no other provider is registered. Consumers using `trace.getTracer(…)` from `@opentelemetry/api` MUST receive the Suaveplan tracer.

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

@@ -0,0 +1,60 @@
+# Tasks: enterprise-opentelemetry
+
+## 1. Scaffold
+
+- [x] 1.1 `universal/platform/opentelemetry/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+
+- [x] 2.1 `src/error-codes.ts` — `OTEL.*` codes.
+- [x] 2.2 Zod schemas for wire-format types.
+
+## 3. Constants + types
+
+- [x] 3.1 `src/constants/index.ts`.
+- [x] 3.2 `src/types/common.ts` — all enums + union shapes.
+
+## 4. Utils
+
+- [x] 4.1 `src/utils/id-generator.ts` — `generateSpanId`, `generateTraceId`, `isValidSpanId`, `isValidTraceId`, `hrTimeMs`.
+
+## 5. Context
+
+- [x] 5.1 `src/core/context/context.ts` — `Context`, `ContextManager`, span-in-context helpers.
+
+## 6. Tracer + span
+
+- [x] 6.1 `src/core/span/span.ts` — `Span` class.
+- [x] 6.2 `src/core/tracer/tracer.ts` — `Tracer`, `TracerProvider`.
+
+## 7. Meter
+
+- [x] 7.1 `src/core/meter/meter.ts` — `Counter`, `Gauge`, `Histogram`, `Meter`, `MeterProvider`.
+
+## 8. Propagation
+
+- [x] 8.1 `src/propagation/baggage/baggage.ts` — full baggage lifecycle + W3C propagator.
+- [x] 8.2 `src/propagation/w3c/w3c.ts` — W3C Trace Context propagator.
+
+## 9. Exporters
+
+- [x] 9.1 `src/exporters/console/console.ts` — `ConsoleSpanExporter`.
+- [x] 9.2 `src/exporters/memory/memory.ts` — `InMemorySpanExporter`.
+
+## 10. Error bridge
+
+- [x] 10.1 `src/error-bridge/error-bridge.ts` — installs global `SuaveplanError` interceptor recording span events.
+
+## 11. `@opentelemetry/api` compatibility
+
+- [x] 11.1 Global-provider registration on import for drop-in use.
+
+## 12. Docs / barrel / subpath exports / README
+
+## 13. Benchmarks
+
+- [x] 13.1 Span start/end hot path; meter counter/histogram record hot path.
+
+## 14. Ship gate
+
+- [x] 14.1 Verification sequence; fold + archive.