@forgeax/engine-profiler 0.0.0-dev.8d955ade1c79

package/src/__tests__/fixtures/profile-capture/invalid-boundary.json

@@ -0,0 +1,144 @@
+{
+  "cases": [
+    {
+      "name": "unsupported schema version",
+      "capture": { "schemaVersion": "2.0" }
+    },
+    {
+      "name": "zero frame limit",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0003",
+        "timeUnit": "microseconds",
+        "frameLimit": 0,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": [], "render": [] },
+        "records": [],
+        "completeness": {
+          "status": "partial",
+          "retainedEventCount": 0,
+          "droppedEventCount": 0,
+          "incompleteReason": "stopped-before-frame"
+        }
+      }
+    },
+    {
+      "name": "fractional event limit",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0004",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1.5,
+        "phaseCatalog": { "app": [], "render": [] },
+        "records": [],
+        "completeness": {
+          "status": "partial",
+          "retainedEventCount": 0,
+          "droppedEventCount": 0,
+          "incompleteReason": "stopped-before-frame"
+        }
+      }
+    },
+    {
+      "name": "negative duration",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0005",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": ["input"], "render": [] },
+        "records": [
+          {
+            "kind": "phase",
+            "source": "app",
+            "frameId": 1,
+            "phase": "input",
+            "startMicros": 20,
+            "endMicros": 10,
+            "durationMicros": -10
+          }
+        ],
+        "completeness": { "status": "complete", "retainedEventCount": 1, "droppedEventCount": 0 }
+      }
+    },
+    {
+      "name": "unknown phase",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0006",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": ["input"], "render": [] },
+        "records": [
+          {
+            "kind": "skip",
+            "source": "app",
+            "frameId": 1,
+            "phase": "unknown",
+            "reason": "not-declared"
+          }
+        ],
+        "completeness": {
+          "status": "partial",
+          "retainedEventCount": 1,
+          "droppedEventCount": 0,
+          "incompleteReason": "phase-not-declared"
+        }
+      }
+    },
+    {
+      "name": "complete with incomplete reason",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0007",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": [], "render": [] },
+        "records": [],
+        "completeness": {
+          "status": "complete",
+          "retainedEventCount": 0,
+          "droppedEventCount": 0,
+          "incompleteReason": "source-failed"
+        }
+      }
+    },
+    {
+      "name": "frame id is not positive safe integer",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0008",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": ["input"], "render": [] },
+        "records": [
+          { "kind": "skip", "source": "app", "frameId": -1, "phase": "input", "reason": "not-run" }
+        ],
+        "completeness": {
+          "status": "partial",
+          "retainedEventCount": 1,
+          "droppedEventCount": 0,
+          "incompleteReason": "source-failed"
+        }
+      }
+    },
+    {
+      "name": "overflow without affected frame range",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0009",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": [], "render": [] },
+        "records": [],
+        "completeness": { "status": "overflow", "retainedEventCount": 0, "droppedEventCount": 1 }
+      }
+    }
+  ]
+}

package/src/__tests__/fixtures/profile-capture/model-input.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0010",
+  "timeUnit": "microseconds",
+  "frameLimit": 2,
+  "eventLimit": 8,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1030,
+      "durationMicros": 30
+    },
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "update",
+      "startMicros": 1100,
+      "endMicros": 1120,
+      "durationMicros": 20
+    },
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 2,
+      "phase": "input",
+      "startMicros": 2000,
+      "endMicros": 2010,
+      "durationMicros": 10
+    },
+    {
+      "kind": "skip",
+      "source": "render",
+      "frameId": 2,
+      "phase": "submit",
+      "reason": "no-render"
+    }
+  ],
+  "completeness": {
+    "status": "overflow",
+    "retainedEventCount": 4,
+    "droppedEventCount": 2,
+    "firstAffectedFrameId": 2,
+    "lastAffectedFrameId": 2
+  }
+}

package/src/__tests__/fixtures/profile-capture/sink-failure.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0004",
+  "timeUnit": "microseconds",
+  "frameLimit": 2,
+  "eventLimit": 4,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1100,
+      "durationMicros": 100
+    }
+  ],
+  "completeness": {
+    "status": "partial",
+    "retainedEventCount": 1,
+    "droppedEventCount": 0,
+    "incompleteReason": "profile-sink-failed",
+    "firstAffectedFrameId": 1,
+    "lastAffectedFrameId": 1
+  }
+}

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

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0001",
+  "timeUnit": "microseconds",
+  "frameLimit": 2,
+  "eventLimit": 8,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1100,
+      "durationMicros": 100
+    },
+    {
+      "kind": "skip",
+      "source": "render",
+      "frameId": 1,
+      "phase": "submit",
+      "reason": "no-render"
+    },
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 2,
+      "phase": "update",
+      "startMicros": 2000,
+      "endMicros": 2200,
+      "durationMicros": 200
+    }
+  ],
+  "completeness": {
+    "status": "complete",
+    "retainedEventCount": 3,
+    "droppedEventCount": 0
+  }
+}

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' } } },
+    });
+  });
+});