# 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.