Initial Commit

openspec/changes/opentelemetry-completion/tasks.md

@@ -0,0 +1,112 @@
+# Tasks — OpenTelemetry completion
+
+> Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened.
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## Audit Note (2026-05-02)
+
+Status: **DEFERRED**. `packages/monitor/opentelemetry/src/` contains `core` (with `propagation` + `sdk`), `errors`, `schemas`, and `utils` (`metrics-utils`, `resource`, `span-utils`). None of the five proposed additions exist: no `exporters/` directory (no `InMemorySpanExporter`, no `ConsoleSpanExporter`), no `id-generator/` (no `generateTraceId` / `generateSpanId` / `createDeterministicIdGenerator`), no `baggage/` (no `W3CBaggagePropagator`, no `serializeBaggage` / `parseBaggage`). The `OTEL.EXPORT_FAILED` / `OTEL.INVALID_TRACE_ID` / `OTEL.INVALID_SPAN_ID` error codes are also absent. 0% of work is done.
+
+## 1. Spec authoring
+
+- [ ] 1.1 Read `openspec/archive/2026-04-19-enterprise-opentelemetry/proposal.md` end-to-end to confirm what was committed and what slipped
+- [ ] 1.2 Read `openspec/AGENTS.md` Sections 13 (spec-conformance audit) and 14 (source mapping for migrations); §14a (proposal must list affected dependents)
+- [ ] 1.3 Draft `proposal.md` from `openspec/templates/proposal.md` — include the `## Position on the legacy substrate` rationale (out-of-scope items justified)
+- [ ] 1.4 Fill `## Source mapping` with upstream line ranges for each ADDED requirement; every "no source line" requirement justified
+- [ ] 1.5 Draft `specs/opentelemetry/spec.md` from `openspec/templates/spec-delta.md` — five ADDED requirements: in-memory exporter, console exporter, id-generator, deterministic id-generator, baggage propagator
+- [ ] 1.6 Every requirement in the spec delta carries a `**Verified by:**` line naming concrete `it(...)` titles
+- [ ] 1.7 Draft `## Migration` section in `proposal.md` listing legacy `Tracer` / `Meter` / `error-bridge` consumers and their replacement path
+- [ ] 1.8 `bunx openspec change validate opentelemetry-completion` exits with no errors
+
+## 2. Implementation — exporters
+
+- [ ] 2.1 Add `@opentelemetry/sdk-trace-base` to `packages/monitor/opentelemetry/package.json` `dependencies` via `catalog:observability` (verify the catalog entry exists; add it if missing)
+- [ ] 2.2 Create `packages/monitor/opentelemetry/src/exporters/memory/memory.ts` implementing `InMemorySpanExporter` against the `SpanExporter` interface from `@opentelemetry/sdk-trace-base`
+- [ ] 2.3 Provide `getFinishedSpans()`, `getSpansByName(name)`, `reset()`, `shutdown()`, `forceFlush()`, `spanCount` getter
+- [ ] 2.4 Make `shutdown()` idempotent; subsequent `export()` calls return `ExportResultCode.FAILED` with `OpenTelemetryError(OTEL.EXPORT_FAILED, ...)` as the `error` field
+- [ ] 2.5 Create `packages/monitor/opentelemetry/src/exporters/console/console.ts` implementing `ConsoleSpanExporter` and `ConsoleSpanExporterOptions`
+- [ ] 2.6 Default `logFn` to `console.log`; default `pretty` to `true`; render span kind, status code, ISO start/end times, duration, attributes, events, links, resource attributes
+- [ ] 2.7 Apply the same post-shutdown `OTEL.EXPORT_FAILED` rule to the console exporter
+- [ ] 2.8 Add `OTEL.EXPORT_FAILED` to `packages/monitor/opentelemetry/src/errors/opentelemetry-error.ts` `OTEL_CODES`
+
+## 3. Implementation — id-generator
+
+- [ ] 3.1 Create `packages/monitor/opentelemetry/src/id-generator/id-generator.ts` exporting `generateTraceId`, `generateSpanId`, `isValidTraceId`, `isValidSpanId`
+- [ ] 3.2 Generation uses `crypto.getRandomValues` exclusively; throws `OpenTelemetryError(OTEL.INVALID_TRACE_ID, ...)` (or `INVALID_SPAN_ID`) if the host has no `crypto.getRandomValues` (genesis determinism rule — no `Math.random()` fallback)
+- [ ] 3.3 Re-roll on the all-zero value; cap at 8 attempts; if exceeded, throw `OTEL.INVALID_TRACE_ID` / `INVALID_SPAN_ID`
+- [ ] 3.4 Add `INVALID_TRACE_ID` / `INVALID_SPAN_ID` / `TRACE_ID_HEX_LENGTH` / `SPAN_ID_HEX_LENGTH` constants in `packages/monitor/opentelemetry/src/constants/trace.ts`
+- [ ] 3.5 Create `packages/monitor/opentelemetry/src/id-generator/deterministic.ts` exporting `createDeterministicIdGenerator(rng: Rng): { generateTraceId: () => string; generateSpanId: () => string }`
+- [ ] 3.6 Use the supplied `Rng.bytes(n)` to fill the trace / span ID; preserve the all-zero retry budget; route exhaustion through the same error codes
+- [ ] 3.7 Add `OTEL.INVALID_TRACE_ID` and `OTEL.INVALID_SPAN_ID` to `OTEL_CODES`
+
+## 4. Implementation — baggage
+
+- [ ] 4.1 Create `packages/monitor/opentelemetry/src/baggage/baggage.ts` exporting `W3CBaggagePropagator`, `serializeBaggage`, `parseBaggage`, `BAGGAGE_HEADER`
+- [ ] 4.2 `W3CBaggagePropagator` implements `TextMapPropagator` from `@opentelemetry/api`; `extract(context, carrier, getter)`, `inject(context, carrier, setter)`, `fields()` returning `["baggage"]`
+- [ ] 4.3 `inject` reads the active baggage via `propagation.getBaggage(context)`; serialises with URI-encoding; calls `setter.set(carrier, BAGGAGE_HEADER, value)`; no-op if the baggage is empty
+- [ ] 4.4 `extract` reads `carrier[BAGGAGE_HEADER]` (handling string-array carrier values); parses; sets via `propagation.setBaggage(context, baggage)`
+- [ ] 4.5 Honour `MAX_BAGGAGE_ENTRIES` / `MAX_BAGGAGE_KEY_LENGTH` / `MAX_BAGGAGE_VALUE_LENGTH` caps; entries past the cap are silently ignored (matches legacy and W3C tolerant-parser behaviour)
+- [ ] 4.6 Add the cap constants to `packages/monitor/opentelemetry/src/constants/baggage.ts`
+
+## 5. Wiring
+
+- [ ] 5.1 Update `packages/monitor/opentelemetry/src/index.ts` to re-export every new symbol
+- [ ] 5.2 Update `packages/monitor/opentelemetry/package.json` `exports` map: add `./exporters`, `./id-generator`, `./baggage`, `./constants` subpath entries
+- [ ] 5.3 Add a top-level re-export of `trace`, `metrics`, `context`, `propagation` from `@opentelemetry/api` (Migration §1 — the convenience layer for consumers expecting the legacy substrate's classes)
+- [ ] 5.4 Update root `README.md` (`packages/monitor/opentelemetry/README.md`) `## Modules` section to link the new co-located `.md` files
+
+## 6. Tests
+
+- [ ] 6.1 `src/exporters/memory/memory.test.ts` — collect, query-by-name, reset, shutdown idempotency, post-shutdown export rejection, forceFlush
+- [ ] 6.2 `src/exporters/memory/memory.spec-conformance.test.ts` — pin the `SpanExporter` contract from `@opentelemetry/sdk-trace-base` (export signature, shutdown returns Promise, forceFlush returns Promise)
+- [ ] 6.3 `src/exporters/console/console.test.ts` — default logFn, custom logFn, pretty / compact rendering, post-shutdown rejection
+- [ ] 6.4 `src/exporters/console/console.spec-conformance.test.ts` — same SpanExporter contract pin
+- [ ] 6.5 `src/id-generator/id-generator.test.ts` — length, charset, non-zero invariant; `isValidTraceId` / `isValidSpanId` accept/reject
+- [ ] 6.6 `src/id-generator/id-generator.spec-conformance.test.ts` — `fast-check` property `∀ id: isValidTraceId(generateTraceId())` over 1000 samples
+- [ ] 6.7 `src/id-generator/deterministic.test.ts` — seeded `Rng` produces reproducible IDs across two calls
+- [ ] 6.8 `src/id-generator/deterministic.spec-conformance.test.ts` — supplied `Rng` that always yields zero bytes throws `OTEL.INVALID_TRACE_ID` after the 8-attempt budget
+- [ ] 6.9 `src/baggage/baggage.test.ts` — `W3CBaggagePropagator` round-trip extract/inject, URI-encoding round-trip for `key with space=value;with semicolon`
+- [ ] 6.10 `src/baggage/baggage.spec-conformance.test.ts` — `MAX_BAGGAGE_ENTRIES` cap silently drops the 181st entry; key longer than `MAX_BAGGAGE_KEY_LENGTH` is dropped; value longer than `MAX_BAGGAGE_VALUE_LENGTH` is dropped
+- [ ] 6.11 Every `it(...)` in 6.1-6.10 carries `{ timeout: 5000 }`
+
+## 7. Documentation
+
+- [ ] 7.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
+- [ ] 7.2 README links every co-located `.md` under `## Modules`
+- [ ] 7.3 README `## Features` enumerates the five new capabilities
+- [ ] 7.4 Update `CLAUDE.md` package listing for `@suaveplan/opentelemetry` to include the new exports
+
+## 8. Pre-archive verification (the 5-gate triple)
+
+- [ ] 8.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
+- [ ] 8.2 `bunx turbo lint typecheck test --filter=@suaveplan/opentelemetry` — green
+- [ ] 8.3 `bunx turbo test:coverage --filter=@suaveplan/opentelemetry` — 100/100/100/100
+- [ ] 8.4 `bun scripts/openspec-conformance.ts @suaveplan/opentelemetry` — exit 0, no `error` findings
+- [ ] 8.5 `bunx turbo build --filter=@suaveplan/opentelemetry` — green
+
+## 9. Pre-archive 7-row checklist (AGENTS.md Section 13)
+
+- [ ] 9.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim (e.g. `OTEL_CODES` keys)
+- [ ] 9.2 Zod schemas wired at every declared boundary (constructor options for both exporters; baggage cap config)
+- [ ] 9.3 Every error code in `OTEL_CODES` thrown by at least one production path (`OTEL.EXPORT_FAILED`, `OTEL.INVALID_TRACE_ID`, `OTEL.INVALID_SPAN_ID` — covered above)
+- [ ] 9.4 Strict-mode behaviors tested on and off (post-shutdown export, retry-budget exhaustion)
+- [ ] 9.5 OTel instruments emitted from production paths and asserted with the new `InMemorySpanExporter` (eat your own dogfood — `withSpan` test in `src/utils/span-utils.test.ts` adopts it)
+- [ ] 9.6 Lifecycle dedup tested where claimed (idempotent `shutdown()` on both exporters)
+- [ ] 9.7 No retroactive tick — every box above reflects work done in this change
+
+## 10. Dependent sweep
+
+- [ ] 10.1 `bunx turbo test --filter=...@suaveplan/opentelemetry` — green; `@suaveplan/events-metrics` continues to pass
+- [ ] 10.2 Migrate any in-tree consumer that hand-rolled an in-memory span exporter to use the new `InMemorySpanExporter`. Run: `grep -rln "InMemorySpanExporter\|SimpleSpanProcessor\|BatchSpanProcessor" packages/ src/ --include="*.ts"` and verify no duplicate impl exists
+- [ ] 10.3 If any dependent currently mocks `@opentelemetry/sdk-trace-base`, replace with the real `InMemorySpanExporter` in a follow-up commit (per the genesis "no mocks" rule)
+
+## 11. Archive
+
+- [ ] 11.1 Fold `specs/opentelemetry/spec.md` into `openspec/specs/opentelemetry/spec.md`
+- [ ] 11.2 Move `openspec/changes/opentelemetry-completion/` → `openspec/archive/<yyyy-mm-dd>-opentelemetry-completion/`
+- [ ] 11.3 Refresh `MANIFEST.md` if package set or deps changed (this change adds `@opentelemetry/sdk-trace-base` as a dep)