# Tasks: enterprise-profiler

**Change ID**: enterprise-profiler
**Package**: `@suaveplan/profiler`
**Target path**: `universal/platform/profiler`
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`

---

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

## 1. Scaffold

- [ ] Create `universal/platform/profiler/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
- [ ] Write `package.json` at version `0.1.0`:
  - `"type": "module"`, `"sideEffects": false`
  - `exports` map: `"."` barrel + `"./core/profiler/profiler"`, `"./core/session/session"`, `"./sinks/console-sink/console-sink"`, `"./sinks/json-sink/json-sink"`, `"./utils/aggregate"`, `"./utils/flamegraph"`, `"./types/common"`
  - `dependencies`: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/logger workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
  - `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `fast-check catalog:testing`, `mitata catalog:testing`, `@suaveplan/testing workspace:^`
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
- [ ] Write `vitest.config.ts` using `createTestConfig()`.
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`, `bench` scripts.

---

## 2. Types and error codes

- [ ] Define all public types in `src/types/common.ts`: `ProfileSample`, `StackFrame`, `ProfileSession`, `FlamegraphNode`, `ProfileAggregate`, `ProfilerOptions`, `SessionOptions`, `ProfilerSink`, `ConsoleSinkOptions`, `JsonSinkOptions`.
- [ ] Write `src/types/common.md` (≥200 words, simple + advanced examples).
- [ ] Define error codes in `src/error-codes.ts`: `ProfilerErrorCode` union, metadata, `registerProfilerErrorCodes()`.
- [ ] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.

---

## 3. Aggregate utilities (`src/utils/aggregate.ts`)

- [ ] Implement `aggregateSamples(samples)`: compute count, totalCpuMs, avgCpuMs, p50/p95/p99 (insertion-sort on the cpu array), peakHeapMb, avgHeapMb.
- [ ] Implement `formatDuration(ms)`: format as `Xms`, `Xs`, `Xm Xs`.
- [ ] Write `aggregate.test.ts` (≤500 lines): empty array, single sample, percentile correctness for known data.
- [ ] Write `aggregate.md` (≥200 words).

---

## 4. Flamegraph utilities (`src/utils/flamegraph.ts`)

- [ ] Implement `buildFlamegraph(session)`: group samples by stack frame path, build tree by folding frames into children.
- [ ] Each node's `value` = number of samples that include this frame.
- [ ] Produce sorted children (descending by value).
- [ ] Write `flamegraph.test.ts` (≤500 lines): empty session, single frame, multi-frame stacks, shared frames merge correctly.
- [ ] Write `flamegraph.md` (≥200 words).

---

## 5. Profiler session (`src/core/session/`)

- [ ] Implement `ProfilerSession` (internal class):
  - `sample()` — captures `clock.now()` + heap stats via `process.memoryUsage()` (guarded for non-Node runtimes); returns `ProfileSample`.
  - `stop()` — sets `endTime`, returns immutable `ProfileSession` snapshot.
  - `export('json', signal?)` — JSON-serialises session.
  - `export('flamegraph', signal?)` — calls `buildFlamegraph`, JSON-serialises.
  - `toFlamegraph()` — synchronous `buildFlamegraph` call.
- [ ] Write `session.test.ts` (≤500 lines): sample, stop, export json, export flamegraph, abort on export.
- [ ] Write `session.md` (≥200 words).

---

## 6. Profiler (`src/core/profiler/`)

- [ ] Implement `createProfiler(options?)`: validates options with Zod; stores sessions in `Map<string, ProfilerSession>`.
- [ ] Implement `profiler.startSession(name, options?)` — generates UUID id, stores session, emits OTel span `profiler.session.start`.
- [ ] Implement `profiler.getSession(id)`, `listSessions()`, `clearSessions()`.
- [ ] Implement `profiler.use(sink)` — registers sink; on session stop, calls `sink.onSessionEnd(session)` asynchronously.
- [ ] On session stop, emit OTel span `profiler.session.stop`, histogram `profiler.session_duration_ms`.
- [ ] Write `profiler.test.ts` (≤500 lines): session lifecycle, sink called on stop, multiple sessions.
- [ ] Write `profiler.md` (≥200 words).

---

## 7. Sinks (`src/sinks/`)

### 7a. Console sink

- [ ] Implement `createConsoleSink(options?)` — on session end, prints a summary table via `console.log` with aggregate stats.
- [ ] Write `console-sink.test.ts`: output contains session name and p95 duration.
- [ ] Write `console-sink.md`.

### 7b. JSON sink

- [ ] Implement `createJsonSink(options: { path: string })` — on session end, appends JSON line to file via `Bun.write` (or `fs.appendFile` fallback).
- [ ] Write `json-sink.test.ts`: file written, valid JSON, append-safe.
- [ ] Write `json-sink.md`.

---

## 8. Property-based tests (`tests/property.test.ts`)

- [ ] `aggregateSamples` invariants: avg ≤ max, p50 ≤ p95 ≤ p99, count equals input length.
- [ ] `buildFlamegraph` node value sum: root node value ≤ total samples.
- [ ] Session stop idempotency: calling `stop()` twice on a session should be a no-op after the first call (endTime does not change).

---

## 9. Benchmarks (`src/__benchmarks__/profiler.bench.ts`)

- [ ] `sample_hot`: 1000 `session.sample()` calls.
- [ ] `buildFlamegraph_1k`, `buildFlamegraph_10k`: flamegraph on 1k and 10k sample sessions.
- [ ] `aggregateSamples_1k`, `aggregateSamples_10k`: aggregate on 1k and 10k samples.

---

## 10. Docs

- [ ] All per-file `.md` files per layout in `proposal.md`.
- [ ] `universal/platform/profiler/README.md`: purpose, installation, quick-start, API section, dependency table, benchmarks table.

---

## 11. Verify and publish

- [ ] `bunx turbo lint --filter=@suaveplan/profiler` — zero errors.
- [ ] `bunx turbo typecheck --filter=@suaveplan/profiler` — zero errors.
- [ ] `bunx turbo test --filter=@suaveplan/profiler` — all tests pass.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/profiler` — 100% on all touched modules.
- [ ] `bun run docs:check --filter=@suaveplan/profiler` — zero errors.
- [ ] `bun scripts/publish.ts --package @suaveplan/profiler`.
- [ ] Update `CLAUDE.md` package listing.
- [ ] Archive: move `openspec/changes/enterprise-profiler/` to `openspec/archive/2026-04-24-enterprise-profiler/`.