@forgeax/engine-profiler 0.1.2

package/src/__tests__/fixtures/profile-capture/valid-overflow.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0002",
+  "timeUnit": "microseconds",
+  "frameLimit": 4,
+  "eventLimit": 3,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1100,
+      "durationMicros": 100
+    },
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "update",
+      "startMicros": 1200,
+      "endMicros": 1500,
+      "durationMicros": 300
+    },
+    {
+      "kind": "skip",
+      "source": "render",
+      "frameId": 1,
+      "phase": "submit",
+      "reason": "no-render"
+    }
+  ],
+  "completeness": {
+    "status": "overflow",
+    "retainedEventCount": 3,
+    "droppedEventCount": 7,
+    "firstAffectedFrameId": 2,
+    "lastAffectedFrameId": 4
+  }
+}

package/src/__tests__/generated-freshness.test.ts

@@ -0,0 +1,14 @@
+// @perf-budget-skip: intentional generated-artifact freshness subprocess gate.
+
+import { spawnSync } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+
+describe('generated profile types freshness', () => {
+  it('matches the current profile capture schema', () => {
+    const result = spawnSync(process.execPath, ['scripts/generate-profile-types.mjs', '--check'], {
+      cwd: new URL('../..', import.meta.url),
+      encoding: 'utf8',
+    });
+    expect(result.status, result.stderr).toBe(0);
+  });
+});

package/src/__tests__/model-determinism.test.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { buildProfileModel } from '../model.js';
+
+type CaptureFixture = Record<string, unknown>;
+
+function readFixture(): CaptureFixture {
+  return JSON.parse(
+    readFileSync(new URL('./fixtures/profile-capture/model-input.json', import.meta.url), 'utf8'),
+  ) as CaptureFixture;
+}
+
+function expectOk<T>(result: { ok: boolean; value?: T; error?: { code: string } }): T {
+  expect(result.ok).toBe(true);
+  if (!result.ok) throw new Error(result.error?.code ?? 'unexpected profiler error');
+  return result.value as T;
+}
+
+describe('buildProfileModel determinism contract', () => {
+  it('does not mutate input and returns deeply equal output on repeated calls', () => {
+    const capture = readFixture();
+    const before = JSON.stringify(capture);
+    const first = expectOk(buildProfileModel(capture));
+    const second = expectOk(buildProfileModel(capture));
+
+    expect(second).toEqual(first);
+    expect(JSON.stringify(capture)).toBe(before);
+  });
+
+  it('derives summary, frame, phase and nearest-rank p95 data', () => {
+    const model = expectOk(buildProfileModel(readFixture()));
+
+    expect(model.summary.captureId).toBe('capture-0010');
+    expect(model.summary.completeness.status).toBe('overflow');
+    expect(model.summary.frameRange).toEqual({ first: 1, last: 2 });
+    expect(model.summary.frameCount).toBe(2);
+    expect(model.summary.p95DurationMicros).toBe(30);
+    expect(model.frames).toHaveLength(2);
+    expect(model.frames[0]?.frameId).toBe(1);
+    expect(model.frames[0]?.phaseCount).toBe(2);
+    expect(model.phases).toEqual([
+      { source: 'app', phase: 'input', count: 2, skipCount: 0, p95DurationMicros: 30 },
+      { source: 'app', phase: 'update', count: 1, skipCount: 0, p95DurationMicros: 20 },
+      { source: 'render', phase: 'submit', count: 0, skipCount: 1, p95DurationMicros: null },
+    ]);
+  });
+
+  it('preserves partial and overflow completeness for empty and truncated captures', () => {
+    const fixture = readFixture();
+    const partial = {
+      ...fixture,
+      captureId: 'capture-0011',
+      records: [],
+      completeness: {
+        status: 'partial',
+        retainedEventCount: 0,
+        droppedEventCount: 0,
+        incompleteReason: 'stopped-before-frame',
+      },
+    };
+    const model = expectOk(buildProfileModel(partial));
+
+    expect(model.summary.completeness.status).toBe('partial');
+    expect(model.summary.frameCount).toBe(0);
+    expect(model.summary.frameRange).toBeNull();
+    expect(model.summary.p95DurationMicros).toBeNull();
+    expect(model.completeness.incompleteReason).toBe('stopped-before-frame');
+    expect(model.completeness.droppedEventCount).toBe(0);
+  });
+});

package/src/__tests__/model-query.test.ts

@@ -0,0 +1,128 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { buildProfileModel } from '../model.js';
+
+type CaptureFixture = Record<string, unknown>;
+
+function readFixture(): CaptureFixture {
+  return JSON.parse(
+    readFileSync(new URL('./fixtures/profile-capture/model-input.json', import.meta.url), 'utf8'),
+  ) as CaptureFixture;
+}
+
+function expectOk<T>(result: { ok: boolean; value?: T; error?: { code: string } }): T {
+  expect(result.ok).toBe(true);
+  if (!result.ok) throw new Error(result.error?.code ?? 'unexpected profiler error');
+  return result.value as T;
+}
+
+describe('buildProfileModel query projection', () => {
+  it('preserves capture identity, limits, completeness, and frame detail', () => {
+    const model = expectOk(buildProfileModel(readFixture()));
+
+    expect(model.summary).toMatchObject({
+      schemaVersion: '1.0',
+      captureId: 'capture-0010',
+      timeUnit: 'microseconds',
+      frameLimit: 2,
+      eventLimit: 8,
+      frameRange: { first: 1, last: 2 },
+      completeness: {
+        status: 'overflow',
+        retainedEventCount: 4,
+        droppedEventCount: 2,
+        firstAffectedFrameId: 2,
+        lastAffectedFrameId: 2,
+      },
+    });
+
+    expect(model.frames).toHaveLength(2);
+    expect(model.frames.find((frame) => frame.frameId === 2)).toMatchObject({
+      frameId: 2,
+      recordCount: 2,
+      phaseCount: 1,
+      skipCount: 1,
+      durationMicros: 10,
+    });
+  });
+
+  it('supports exact source and phase lookup without losing skip records', () => {
+    const fixture = readFixture();
+    const phaseCatalog = fixture.phaseCatalog as { app: string[]; render: string[] };
+    const records = fixture.records as Array<Record<string, unknown>>;
+    const model = expectOk(
+      buildProfileModel({
+        ...fixture,
+        phaseCatalog: { ...phaseCatalog, render: [...phaseCatalog.render, 'input'] },
+        records: [
+          ...records,
+          {
+            kind: 'phase',
+            source: 'render',
+            frameId: 2,
+            phase: 'input',
+            startMicros: 2030,
+            endMicros: 2045,
+            durationMicros: 15,
+          },
+        ],
+        completeness: {
+          ...(fixture.completeness as Record<string, unknown>),
+          retainedEventCount: 5,
+        },
+      }),
+    );
+
+    expect(
+      model.phases.find((phase) => phase.source === 'render' && phase.phase === 'input'),
+    ).toEqual({
+      source: 'render',
+      phase: 'input',
+      count: 1,
+      skipCount: 0,
+      p95DurationMicros: 15,
+    });
+    expect(
+      model.phases.find((phase) => phase.source === 'render' && phase.phase === 'submit'),
+    ).toEqual({
+      source: 'render',
+      phase: 'submit',
+      count: 0,
+      skipCount: 1,
+      p95DurationMicros: null,
+    });
+  });
+
+  it('keeps empty partial captures queryable without inventing a frame', () => {
+    const fixture = readFixture();
+    const model = expectOk(
+      buildProfileModel({
+        ...fixture,
+        captureId: 'capture-0011',
+        records: [],
+        completeness: {
+          status: 'partial',
+          retainedEventCount: 0,
+          droppedEventCount: 0,
+          incompleteReason: 'stopped-before-frame',
+        },
+      }),
+    );
+
+    expect(model.summary).toMatchObject({
+      captureId: 'capture-0011',
+      completeness: {
+        status: 'partial',
+        retainedEventCount: 0,
+        droppedEventCount: 0,
+        incompleteReason: 'stopped-before-frame',
+      },
+      frameRange: null,
+      frameCount: 0,
+      recordCount: 0,
+      p95DurationMicros: null,
+    });
+    expect(model.frames).toEqual([]);
+    expect(model.phases).toEqual([]);
+  });
+});

package/src/__tests__/overflow-long-tail.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+import { runProfilerCli } from '../cli.js';
+import { buildProfileModel } from '../model.js';
+import { createProfiler } from '../profiler.js';
+import type { ProfileCapture } from '../types.js';
+
+const TEST_PHASE_CATALOG = { app: ['frame-total'], render: ['extract'] } as const;
+
+function createClock() {
+  let micros = 0;
+  return {
+    nowMicros() {
+      micros += 10;
+      return micros;
+    },
+  };
+}
+
+function captureAfterFrames(frameCount: number): ProfileCapture {
+  const profiler = createProfiler({ clock: createClock(), phaseCatalog: TEST_PHASE_CATALOG });
+  const started = profiler.startCapture({ frameLimit: frameCount + 1, eventLimit: 4 });
+  expect(started.ok).toBe(true);
+  if (!started.ok) throw new Error(started.error.code);
+
+  for (let frameId = 1; frameId <= frameCount; frameId += 1) {
+    expect(started.value.beginFrame(frameId).ok).toBe(true);
+    expect(started.value.beginPhase({ source: 'app', phase: 'frame-total' }).ok).toBe(true);
+    expect(started.value.endPhase().ok).toBe(true);
+    expect(started.value.beginPhase({ source: 'render', phase: 'extract' }).ok).toBe(true);
+    expect(started.value.endPhase().ok).toBe(true);
+    expect(started.value.endFrame().ok).toBe(true);
+  }
+
+  const finished = started.value.finish();
+  expect(finished.ok).toBe(true);
+  if (!finished.ok) throw new Error(finished.error.code);
+  return finished.value;
+}
+
+describe('profiler overflow long-tail bounded evidence', () => {
+  it('keeps nested ownership explicit without double-counting frame duration', () => {
+    const profiler = createProfiler({
+      clock: createClock(),
+      phaseCatalog: { app: ['frame-total', 'frame-child'], render: [] },
+    });
+    const started = profiler.startCapture({ frameLimit: 1, eventLimit: 8 });
+    expect(started.ok).toBe(true);
+    if (!started.ok) return;
+
+    expect(started.value.beginFrame(1).ok).toBe(true);
+    expect(started.value.beginPhase({ source: 'app', phase: 'frame-total' }).ok).toBe(true);
+    expect(started.value.beginPhase({ source: 'app', phase: 'frame-child' }).ok).toBe(true);
+    expect(started.value.endPhase().ok).toBe(true);
+    expect(started.value.endPhase().ok).toBe(true);
+    expect(started.value.endFrame().ok).toBe(true);
+
+    const finished = started.value.finish();
+    expect(finished.ok).toBe(true);
+    if (!finished.ok) return;
+    const child = finished.value.records.find(
+      (record) => record.kind === 'phase' && record.phase === 'frame-child',
+    );
+    expect(child).toMatchObject({ parentSource: 'app', parentPhase: 'frame-total' });
+
+    const model = buildProfileModel(finished.value);
+    expect(model.ok).toBe(true);
+    if (!model.ok) return;
+    expect(model.value.frames[0]?.durationMicros).toBe(30);
+    expect(model.value.phases).toContainEqual(
+      expect.objectContaining({
+        phase: 'frame-child',
+        parentPhase: 'frame-total',
+        p95DurationMicros: 10,
+      }),
+    );
+
+    const cli = runProfilerCli(
+      ['phase', '--source', 'app', '--phase', 'frame-total'],
+      JSON.stringify(finished.value),
+    );
+    expect(cli.exitCode).toBe(0);
+    expect(JSON.parse(cli.stdout)).toMatchObject({
+      children: [
+        expect.objectContaining({
+          source: 'app',
+          phase: 'frame-child',
+          parentSource: 'app',
+          parentPhase: 'frame-total',
+        }),
+      ],
+    });
+  });
+
+  it('keeps record, model, and CLI storage bounded after a ten-times tail', () => {
+    const overflowTriggerFrame = 3;
+    const postOverflowFrames = 40;
+    const capture = captureAfterFrames(overflowTriggerFrame + postOverflowFrames);
+
+    expect(capture.completeness).toMatchObject({
+      status: 'overflow',
+      retainedEventCount: 4,
+      firstAffectedFrameId: overflowTriggerFrame,
+      lastAffectedFrameId: overflowTriggerFrame + postOverflowFrames,
+    });
+    expect(capture.records).toHaveLength(4);
+    expect(JSON.stringify(capture).length).toBeLessThan(1600);
+
+    const model = buildProfileModel(capture);
+    expect(model.ok).toBe(true);
+    if (!model.ok) return;
+    expect(model.value.summary.completeness).toEqual(capture.completeness);
+    expect(model.value.completeness.status).toBe('overflow');
+
+    const cli = runProfilerCli(['summary'], JSON.stringify(capture));
+    expect(cli.exitCode).toBe(0);
+    expect(cli.stderr).toBe('');
+    expect(JSON.parse(cli.stdout)).toMatchObject({
+      completeness: capture.completeness,
+      frameCount: 2,
+    });
+  });
+
+  it('does not turn an overflow prefix into a complete artifact', () => {
+    const capture = captureAfterFrames(44);
+    expect(capture.completeness.status).not.toBe('complete');
+    expect(buildProfileModel(capture)).toMatchObject({
+      ok: true,
+      value: { summary: { completeness: { status: 'overflow' } } },
+    });
+  });
+});

package/src/__tests__/profile-source-owner.test-d.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { ProfilerError, ProfileSource } from '../index.js';
+import type { RecorderPhaseCatalog } from '../recorder.js';
+
+type ExpectedProfileSource = 'app' | 'render';
+type PhaseCatalogConflict = Extract<ProfilerError, { readonly code: 'phase-catalog-conflict' }>;
+
+const errorsSource = readFileSync(new URL('../errors.ts', import.meta.url), 'utf8');
+const recorderSource = readFileSync(new URL('../recorder.ts', import.meta.url), 'utf8');
+const cliSource = readFileSync(new URL('../cli.ts', import.meta.url), 'utf8');
+
+describe('profiler ProfileSource owner', () => {
+  it('preserves the exact generated vocabulary through the public projection', () => {
+    expectTypeOf<ProfileSource>().toEqualTypeOf<ExpectedProfileSource>();
+
+    const acceptProfileSource = (source: ProfileSource): ProfileSource => source;
+    expect(acceptProfileSource('app')).toBe('app');
+    expect(acceptProfileSource('render')).toBe('render');
+    // @ts-expect-error ProfileSource intentionally excludes additional sources.
+    acceptProfileSource('ecs');
+  });
+
+  it('derives the public error and recorder views from ProfileSource', () => {
+    expectTypeOf<PhaseCatalogConflict['detail']['source']>().toEqualTypeOf<ProfileSource>();
+    expectTypeOf<keyof RecorderPhaseCatalog>().toEqualTypeOf<ProfileSource>();
+    expectTypeOf<ProfileSource>().toEqualTypeOf<keyof RecorderPhaseCatalog>();
+  });
+
+  it('keeps private recorder and CLI projections on the same owner', () => {
+    expect(errorsSource).toContain('readonly source: ProfileSource;');
+    expect(recorderSource).toContain(
+      'export type RecorderPhaseCatalog = Readonly<Record<ProfileSource, readonly string[]>>;',
+    );
+    expect(recorderSource).toContain(
+      'readonly phaseArrays: Record<ProfileSource, readonly string[]>;',
+    );
+    expect(recorderSource).toContain(
+      'readonly phaseSets: Record<ProfileSource, ReadonlySet<string>>;',
+    );
+    expect(cliSource).toContain('readonly source: ProfileSource;');
+    expect(cliSource).toContain('source: ProfileSource | undefined;');
+    expect(cliSource).toContain('source: state.source as ProfileSource');
+  });
+});

package/src/__tests__/profiler-error-owner.test-d.ts

@@ -0,0 +1,64 @@
+import { expectTypeOf, test } from 'vitest';
+import type { ProfilerError, ProfilerErrorCode } from '../index.js';
+
+type ExpectedProfilerErrorCode =
+  | 'capture-boundary-invalid'
+  | 'capture-already-active'
+  | 'profiler-not-enabled'
+  | 'phase-catalog-conflict'
+  | 'profile-source-failed'
+  | 'profile-sink-failed'
+  | 'capture-state-invalid';
+
+expectTypeOf<ProfilerErrorCode>().toEqualTypeOf<ExpectedProfilerErrorCode>();
+expectTypeOf<ProfilerErrorCode>().toEqualTypeOf<ProfilerError['code']>();
+
+test('rejects a code outside the exact public vocabulary', () => {
+  // @ts-expect-error Unknown profiler error codes are not assignable.
+  const invalidCode: ProfilerErrorCode = 'profiler-code-does-not-exist';
+  void invalidCode;
+});
+
+test('narrows every detail payload by exhaustive code switch', () => {
+  const readDetail = (error: ProfilerError): string => {
+    switch (error.code) {
+      case 'capture-boundary-invalid':
+        expectTypeOf(error.detail).toEqualTypeOf<{
+          readonly frameLimit: unknown;
+          readonly eventLimit: unknown;
+        }>();
+        return `${String(error.detail.frameLimit)}:${String(error.detail.eventLimit)}`;
+      case 'capture-already-active':
+        expectTypeOf(error.detail).toEqualTypeOf<{ readonly captureId: string }>();
+        return error.detail.captureId;
+      case 'profiler-not-enabled':
+        expectTypeOf(error.detail).toEqualTypeOf<{ readonly enabled: false }>();
+        return String(error.detail.enabled);
+      case 'phase-catalog-conflict':
+        expectTypeOf(error.detail).toEqualTypeOf<{
+          readonly source: 'app' | 'render';
+          readonly expected: readonly string[];
+          readonly actual: readonly string[];
+        }>();
+        return `${error.detail.source}:${error.detail.expected.join(',')}:${error.detail.actual.join(',')}`;
+      case 'profile-source-failed':
+        expectTypeOf(error.detail).toEqualTypeOf<{
+          readonly source: string;
+          readonly phase: string;
+          readonly frameId: number;
+        }>();
+        return `${error.detail.source}:${error.detail.phase}:${error.detail.frameId}`;
+      case 'profile-sink-failed':
+        expectTypeOf(error.detail).toEqualTypeOf<{ readonly message: string }>();
+        return error.detail.message;
+      case 'capture-state-invalid':
+        expectTypeOf(error.detail).toEqualTypeOf<{ readonly operation: string }>();
+        return error.detail.operation;
+    }
+
+    const exhaustive: never = error;
+    return exhaustive;
+  };
+
+  void readDetail;
+});

package/src/__tests__/published-entry.browser.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error The regression intentionally imports the built .mjs artifact;
+// TypeScript does not map an explicit .mjs path to the sibling generated .d.ts.
+import { createProfiler, validateProfileCapture } from '../../dist/index.mjs';
+
+describe('published profiler browser entry', () => {
+  it('loads the built ESM entry and validates a real capture', () => {
+    const profiler = createProfiler({
+      phaseCatalog: { app: ['frame-total'], render: [] },
+    });
+    const started = profiler.startCapture({ frameLimit: 1, eventLimit: 8 });
+    expect(started.ok).toBe(true);
+    if (!started.ok) return;
+
+    const session = started.value;
+    expect(session.beginFrame(1).ok).toBe(true);
+    expect(session.beginPhase({ source: 'app', phase: 'frame-total' }).ok).toBe(true);
+    expect(session.endPhase().ok).toBe(true);
+    expect(session.endFrame().ok).toBe(true);
+
+    const capture = profiler.latestCapture();
+    expect(capture?.records.length).toBeGreaterThan(0);
+    const validated = validateProfileCapture(capture);
+    expect(validated.ok).toBe(true);
+  });
+});