Initial Commit

openspec/archive/2026-05-24-profiler/proposal.md

@@ -0,0 +1,45 @@
+# Proposal — Migrate @suaveplan/profiler to genesis
+
+## Why
+
+`@suaveplan/profiler` is the universal-tier runtime performance profiling primitive consumed by downstream observability tooling. The upstream package at `/mnt/s/web/suaveplan/packages/universal/profiler/` reached 93.95% test coverage and lacks the genesis enterprise gates (`Clock`/`TimersLike`/`LoggerLike` injection, `defineCodes` error registry, OTel meter wiring, Zod-validated boundaries, 100/100/100/100 coverage). This change re-lands the package at `packages/devtools/tooling/profiler/` with the full feature surface and the genesis enterprise contract.
+
+## What
+
+Land `@suaveplan/profiler@0.1.0` with the following modules (one per feature folder, 5-files-per-feature):
+
+- `profiler/` — `Profiler` class: `start`/`stop`/`mark`/`measure`/`measureAsync`
+- `sampler/` — periodic metric sampler with injectable `Clock`+`TimersLike`
+- `memory/` — heap snapshot capture with injectable capture-fn; leak detection
+- `bottleneck/` — hot-path detector + budget-violation finder
+- `comparison/` — diff two profiles; regression/improvement classifier
+- `flamegraph/` — flamegraph JSON tree builder + recursive-call collapse
+- `reporter/` — text formatter + percentile statistics
+- `otel/` — OTLP-compatible span exporter (HTTP `fetch`)
+- `error-codes/` — `PROFILER_CODES` via `defineCodes` + `ProfilerError`
+- `telemetry/` — OTel meter for the profiler itself (counter + histogram)
+- `types/` — shared `ProfileEntry`/`ProfileMark`/`SamplePoint`/etc
+
+## Source mapping
+
+| Upstream file | Genesis file | Notes |
+| --- | --- | --- |
+| `src/profiler/profiler.ts` | `src/profiler/profiler.ts` | `Clock`+`TimersLike` injected; Zod options |
+| `src/sampler/sampler.ts` | `src/sampler/sampler.ts` | `TimersLike.setTimer` replaces `setInterval` |
+| `src/memory/memory-profiler.ts` | `src/memory/memory.ts` | Injectable `HeapCapture` fn replaces global probe |
+| `src/bottleneck/bottleneck-detector.ts` | `src/bottleneck/bottleneck.ts` | Same algorithm, renamed file |
+| `src/comparison/profile-comparator.ts` | `src/comparison/comparison.ts` | Same algorithm |
+| `src/flamegraph/flamegraph-generator.ts` | `src/flamegraph/flamegraph.ts` | Same algorithm |
+| `src/reporter/reporter.ts` | `src/reporter/reporter.ts` | Same algorithm |
+| `src/otel/otel-exporter.ts` | `src/otel/otel.ts` | `fetch` is injectable for tests |
+| `src/index.ts` | `src/index.ts` | Explicit named re-exports only |
+| (none) | `src/error-codes/error-codes.ts` | New — required by genesis rule |
+| (none) | `src/telemetry/telemetry.ts` | New — required by genesis rule |
+
+## Deviations from upstream
+
+1. Upstream uses `@suaveplan/events` `EventEmitter` with variadic tuple payloads. Genesis `@suaveplan/events` exposes `EventBus` with single-payload (`emit(type, payload)`) — event maps reshaped to single-object payloads.
+2. Upstream calls `Date.now()` and `setInterval` directly. Genesis injects `Clock` + `TimersLike` per the universal-tier contract.
+3. Upstream has no error-code registry. Genesis adds `PROFILER_CODES`/`ProfilerError`.
+4. Upstream emits no profiler-self-telemetry. Genesis adds a `telemetry/` module emitting per-public-call counters + duration histograms.
+5. Boundary validation: every public constructor option object is now Zod-validated.