@forgeax/engine-profiler 0.1.2

package/src/__tests__/recorder-contract.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from 'vitest';
+import { createProfiler } from '../profiler.js';
+
+const TEST_PHASE_CATALOG = { app: ['frame-total'], render: ['record'] } as const;
+
+function createClock() {
+  let current = 1000;
+  return {
+    nowMicros() {
+      current += 10;
+      return current;
+    },
+  };
+}
+
+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('bounded profiler recorder contract', () => {
+  it('rejects invalid limits before entering an active capture', () => {
+    const profiler = createProfiler({ clock: createClock(), phaseCatalog: TEST_PHASE_CATALOG });
+
+    for (const limits of [
+      { frameLimit: 0, eventLimit: 1 },
+      { frameLimit: 1, eventLimit: 0 },
+      { frameLimit: -1, eventLimit: 1 },
+      { frameLimit: 1.5, eventLimit: 1 },
+      { frameLimit: Number.POSITIVE_INFINITY, eventLimit: 1 },
+    ]) {
+      const result = profiler.startCapture(limits);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBe('capture-boundary-invalid');
+    }
+    expect(profiler.activeCaptureId()).toBeUndefined();
+  });
+
+  it('keeps one active capture and reports its identity on conflict', () => {
+    const profiler = createProfiler({ clock: createClock(), phaseCatalog: TEST_PHASE_CATALOG });
+    const session = expectOk(profiler.startCapture({ frameLimit: 2, eventLimit: 4 }));
+    const second = profiler.startCapture({ frameLimit: 2, eventLimit: 4 });
+
+    expect(second.ok).toBe(false);
+    if (!second.ok) {
+      expect(second.error.code).toBe('capture-already-active');
+      if (second.error.code === 'capture-already-active') {
+        expect(second.error.detail.captureId).toBe(session.captureId);
+      }
+    }
+    expect(profiler.activeCaptureId()).toBe(session.captureId);
+  });
+
+  it('pairs open phases and preserves a complete bounded artifact', () => {
+    const profiler = createProfiler({ clock: createClock(), phaseCatalog: TEST_PHASE_CATALOG });
+    const session = expectOk(profiler.startCapture({ frameLimit: 1, eventLimit: 2 }));
+
+    expectOk(session.beginFrame(1));
+    expectOk(session.beginPhase({ source: 'app', phase: 'frame-total' }));
+    expectOk(session.endPhase());
+    expectOk(session.endFrame());
+    const artifact = expectOk(session.finish());
+
+    expect(artifact.completeness.status).toBe('complete');
+    expect(artifact.records).toHaveLength(1);
+    expect(artifact.records[0]?.kind).toBe('phase');
+  });
+
+  it('defers capture event object materialization until finish', () => {
+    const allocationReport = { profilerEventObjectAllocations: 0 };
+    const profiler = createProfiler({
+      clock: createClock(),
+      phaseCatalog: TEST_PHASE_CATALOG,
+      allocationReport,
+    });
+    const session = expectOk(profiler.startCapture({ frameLimit: 1, eventLimit: 2 }));
+
+    expectOk(session.beginFrame(1));
+    expectOk(session.beginPhase({ source: 'app', phase: 'frame-total' }));
+    expectOk(session.endPhase());
+    expect(allocationReport.profilerEventObjectAllocations).toBe(0);
+    expectOk(session.endFrame());
+    expectOk(session.finish());
+    expect(allocationReport.profilerEventObjectAllocations).toBe(1);
+  });
+
+  it('accepts a phase catalog registered after capture starts', () => {
+    const profiler = createProfiler({ clock: createClock() });
+    const session = expectOk(profiler.startCapture({ frameLimit: 1, eventLimit: 2 }));
+
+    expectOk(profiler.registerPhaseCatalog('app', TEST_PHASE_CATALOG.app));
+    expectOk(session.beginFrame(1));
+    expectOk(session.beginPhase('app', 'frame-total'));
+    expectOk(session.endPhase());
+    expectOk(session.endFrame());
+    const artifact = expectOk(session.finish());
+
+    expect(artifact.records).toHaveLength(1);
+    expect(artifact.records[0]?.kind).toBe('phase');
+  });
+
+  it('releases a phase catalog lease without mutating a finished capture', () => {
+    const profiler = createProfiler({ clock: createClock() });
+    const release = expectOk(profiler.registerPhaseCatalog('app', TEST_PHASE_CATALOG.app));
+    const session = expectOk(profiler.startCapture({ frameLimit: 1, eventLimit: 2 }));
+
+    expectOk(session.beginFrame(1));
+    expectOk(session.beginPhase('app', 'frame-total'));
+    expectOk(session.endPhase());
+    expectOk(session.endFrame());
+    const artifact = expectOk(session.finish());
+    release();
+    release();
+
+    expect(profiler.phaseCatalog.app).toEqual([]);
+    expect(artifact.phaseCatalog.app).toEqual(TEST_PHASE_CATALOG.app);
+    expect(profiler.registerPhaseCatalog('app', TEST_PHASE_CATALOG.app).ok).toBe(true);
+  });
+
+  it('stops record growth after event overflow while retaining scalar accounting', () => {
+    const profiler = createProfiler({ clock: createClock(), phaseCatalog: TEST_PHASE_CATALOG });
+    const session = expectOk(profiler.startCapture({ frameLimit: 20, eventLimit: 2 }));
+
+    for (let frameId = 1; frameId <= 20; frameId += 1) {
+      expectOk(session.beginFrame(frameId));
+      expectOk(session.recordSkip({ source: 'render', phase: 'record', reason: 'no-render' }));
+      expectOk(session.endFrame());
+    }
+    const artifact = expectOk(session.finish());
+
+    expect(artifact.completeness.status).toBe('overflow');
+    expect(artifact.records.length).toBe(2);
+    expect(artifact.completeness.retainedEventCount).toBe(2);
+    expect(artifact.completeness.droppedEventCount).toBeGreaterThan(0);
+    expect(artifact.completeness.firstAffectedFrameId).toBe(3);
+    expect(artifact.completeness.lastAffectedFrameId).toBe(20);
+  });
+
+  it('returns partial structured errors for a sink Result.err and a sink throw', () => {
+    const sinks = [
+      { write: () => ({ ok: false as const, error: { code: 'profile-sink-failed' as const } }) },
+      {
+        write: () => {
+          throw new Error('sink unavailable');
+        },
+      },
+    ];
+
+    for (const sink of sinks) {
+      const profiler = createProfiler({ clock: createClock(), sink });
+      const session = expectOk(profiler.startCapture({ frameLimit: 1, eventLimit: 1 }));
+      const result = session.finish();
+
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error.code).toBe('profile-sink-failed');
+        expect(result.error.expected).toContain('partial');
+        expect(result.error.hint.length).toBeGreaterThan(0);
+      }
+    }
+  });
+});

package/src/__tests__/schema-contract.test.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { validateProfileCapture } from '../schema.js';
+
+type Fixture = Record<string, unknown>;
+
+function readFixture(name: string): Fixture {
+  return JSON.parse(
+    readFileSync(new URL(`./fixtures/profile-capture/${name}`, import.meta.url), 'utf8'),
+  ) as Fixture;
+}
+
+describe('ProfileCapture schema contract', () => {
+  it('accepts complete and overflow self-describing captures', () => {
+    for (const name of ['valid-complete.json', 'valid-overflow.json']) {
+      const result = validateProfileCapture(readFixture(name));
+      expect(result.ok, `${name} should be valid`).toBe(true);
+    }
+  });
+
+  it('rejects every declared invalid boundary and completeness case', () => {
+    const fixture = readFixture('invalid-boundary.json');
+    const cases = fixture.cases as Array<{ name: string; capture: Fixture }>;
+
+    expect(cases.length).toBeGreaterThanOrEqual(8);
+    for (const testCase of cases) {
+      const result = validateProfileCapture(testCase.capture);
+      expect(result.ok, `${testCase.name} should be rejected`).toBe(false);
+      if (result.ok) continue;
+      expect(result.error.code).toMatch(/^profile-artifact-/);
+    }
+  });
+
+  it('rejects an unknown phase without a second hard-coded phase list', () => {
+    const capture = readFixture('valid-complete.json');
+    const records = capture.records as Fixture[];
+    records[0] = { ...records[0], phase: 'phase-not-in-catalog' };
+
+    const result = validateProfileCapture(capture);
+    expect(result.ok).toBe(false);
+  });
+});

package/src/__tests__/schema-derived-union-owner.test.ts

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+type Schema = { $defs: Record<string, unknown> };
+
+function readSchema(): Schema {
+  return JSON.parse(
+    readFileSync(new URL('../../schema/profile-capture.schema.json', import.meta.url), 'utf8'),
+  ) as Schema;
+}
+
+function literalUnion(values: readonly string[]): string {
+  return values.map((value) => `'${value}'`).join(' | ');
+}
+
+function readStringEnum(definition: unknown): readonly string[] {
+  return (definition as { enum: readonly string[] }).enum;
+}
+
+function readRecordKinds(schema: Schema): readonly string[] {
+  const record = schema.$defs.record as { oneOf: readonly { $ref: string }[] };
+  return record.oneOf.map(({ $ref }) => {
+    const definitionName = $ref.slice('#/$defs/'.length);
+    const definition = schema.$defs[definitionName] as {
+      properties: { kind: { const: string } };
+    };
+    return definition.properties.kind.const;
+  });
+}
+
+describe('schema-derived profiler union owners', () => {
+  it('projects the three closed unions from schema memberships', () => {
+    const schema = readSchema();
+    const source = readFileSync(
+      new URL('../../scripts/generate-profile-types.mjs', import.meta.url),
+      'utf8',
+    );
+    const generated = readFileSync(
+      new URL('../generated/profile-capture.ts', import.meta.url),
+      'utf8',
+    );
+
+    const sourceUnion = literalUnion(readStringEnum(schema.$defs.source));
+    const recordKindUnion = literalUnion(readRecordKinds(schema));
+    const completenessStatus = schema.$defs.completeness as {
+      properties: { status: { enum: readonly string[] } };
+    };
+    const completenessUnion = literalUnion(readStringEnum(completenessStatus.properties.status));
+
+    expect(generated).toContain(`export type ProfileSource = ${sourceUnion};`);
+    expect(generated).toContain(`export type ProfileRecordKind = ${recordKindUnion};`);
+    expect(generated).toContain(`export type ProfileCompletenessStatus = ${completenessUnion};`);
+    expect(source).toContain('schema.$defs.source.enum');
+    expect(source).toContain('schema.$defs.record.oneOf');
+    expect(source).toContain('schema.$defs.completeness.properties.status.enum');
+  });
+});

package/src/browser-user-timing.ts

@@ -0,0 +1,194 @@
+import type { Profiler } from './profiler.js';
+import type { ProfileDetail, RecorderSession } from './recorder.js';
+import type { ProfileCapture, ProfilePhaseStart, ProfileSource } from './types.js';
+
+/** The small browser API surface used by the opt-in User Timing adapter. */
+type UserTiming = { readonly mark: (name: string) => void };
+
+/** Configuration shared by editor and standalone Play browser hosts. */
+export interface UserTimingProfilerOptions {
+  /** Global flag that enables marks. Defaults to the harness diagnostic flag. */
+  readonly diagnosticsKey?: string;
+  /** Stable id written into the optional Profiler capture projection. */
+  readonly captureId?: string;
+  /** Host callback invoked after an owner phase closes. */
+  readonly onPhaseEnd?: (phase: { readonly source: ProfileSource; readonly phase: string }) => void;
+}
+
+type DiagnosticGlobal = Record<string, unknown>;
+type PhaseCatalog = ProfileCapture['phaseCatalog'];
+type BrowserProfileDetail = ProfileDetail;
+const DEFAULT_CAPTURE_ID = 'capture-0001';
+const CAPTURE_ID_PATTERN = /^capture-[0-9]{4,}$/;
+
+function resolveCaptureId(captureId: string | undefined): string {
+  return captureId === undefined || CAPTURE_ID_PATTERN.test(captureId)
+    ? (captureId ?? DEFAULT_CAPTURE_ID)
+    : DEFAULT_CAPTURE_ID;
+}
+
+function partialCapture(captureId: string, phaseCatalog: PhaseCatalog): ProfileCapture {
+  return {
+    schemaVersion: '1.0',
+    captureId,
+    timeUnit: 'microseconds',
+    frameLimit: 1,
+    eventLimit: 1,
+    phaseCatalog,
+    records: [],
+    completeness: {
+      status: 'partial',
+      retainedEventCount: 0,
+      droppedEventCount: 0,
+      incompleteReason: 'user-timing-transport',
+    },
+  };
+}
+
+function diagnosticsEnabled(key: string): boolean {
+  const value = (globalThis as unknown as DiagnosticGlobal)[key];
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { readonly enabled?: unknown }).enabled === true
+  );
+}
+
+function diagnosticsDetail(key: string): BrowserProfileDetail {
+  const value = (globalThis as unknown as DiagnosticGlobal)[key];
+  if (typeof value !== 'object' || value === null) return 'owner';
+  const detail = (value as { readonly detail?: unknown }).detail;
+  return detail === 'nested' || detail === 'passes' ? detail : 'owner';
+}
+
+/**
+ * Creates a zero-cost-while-disabled browser projection of the engine Profiler.
+ *
+ * The engine frame loop remains the phase owner. This adapter only translates
+ * the already-open phases to User Timing marks when a host explicitly enables
+ * the diagnostic flag before app creation. Normal game/editor frames therefore
+ * do not allocate a profiler or call performance.mark().
+ */
+export function createUserTimingProfiler(
+  options: UserTimingProfilerOptions = {},
+): Profiler | undefined {
+  const diagnosticsKey = options.diagnosticsKey ?? '__forgeaxFramePhaseDiagnostics';
+  const captureId = resolveCaptureId(options.captureId);
+  const timingEnabled = diagnosticsEnabled(diagnosticsKey);
+  const detail = diagnosticsDetail(diagnosticsKey);
+  const performanceApi = timingEnabled
+    ? (globalThis as unknown as { readonly performance?: UserTiming }).performance
+    : undefined;
+  if (!timingEnabled && options.onPhaseEnd === undefined) return undefined;
+  if (
+    timingEnabled &&
+    (performanceApi === undefined || typeof performanceApi.mark !== 'function')
+  ) {
+    if (options.onPhaseEnd === undefined) return undefined;
+  }
+
+  let phaseCatalog: PhaseCatalog = { app: [], render: [] };
+  let frameId: number | undefined;
+  let active = true;
+  let latest: ProfileCapture | undefined;
+  const openPhases: Array<{ readonly source: ProfileSource; readonly phase: string }> = [];
+
+  function mark(name: string): void {
+    if (performanceApi === undefined) return;
+    try {
+      performanceApi.mark(name);
+    } catch {
+      // Diagnostics must not change the host frame-loop behavior.
+    }
+  }
+
+  function timingSource(source: ProfileSource): 'frame' | 'render' {
+    return source === 'app' ? 'frame' : 'render';
+  }
+
+  const session = {
+    captureId,
+    detail,
+    beginFrame(nextFrameId: number) {
+      frameId = nextFrameId;
+      openPhases.length = 0;
+      return { ok: true as const, value: undefined };
+    },
+    beginPhase(inputOrSource: ProfilePhaseStart | ProfileSource, phaseName?: string) {
+      if (frameId === undefined) return { ok: true as const, value: undefined };
+      const input =
+        typeof inputOrSource === 'string'
+          ? { source: inputOrSource, phase: phaseName as string }
+          : inputOrSource;
+      openPhases.push(input);
+      mark(`forgeax.${timingSource(input.source)}.phase.${frameId}.${input.phase}.begin`);
+      return { ok: true as const, value: undefined };
+    },
+    endPhase() {
+      const phase = openPhases.pop();
+      if (phase !== undefined) options.onPhaseEnd?.(phase);
+      if (frameId !== undefined && phase !== undefined) {
+        mark(`forgeax.${timingSource(phase.source)}.phase.${frameId}.${phase.phase}.end`);
+      }
+      return { ok: true as const, value: undefined };
+    },
+    recordSkip(input: {
+      readonly source: ProfileSource;
+      readonly phase: string;
+      readonly reason: string;
+    }) {
+      if (frameId !== undefined) {
+        mark(
+          `forgeax.${timingSource(input.source)}.phase.${frameId}.${input.phase}.skip.${input.reason}`,
+        );
+      }
+      return { ok: true as const, value: undefined };
+    },
+    endFrame() {
+      frameId = undefined;
+      openPhases.length = 0;
+      return { ok: true as const, value: undefined };
+    },
+    finish() {
+      latest = partialCapture(captureId, phaseCatalog);
+      active = false;
+      frameId = undefined;
+      openPhases.length = 0;
+      return { ok: true as const, value: latest };
+    },
+  } satisfies RecorderSession;
+
+  return {
+    registerPhaseCatalog(source, phases) {
+      const definition = [...phases];
+      phaseCatalog = { ...phaseCatalog, [source]: definition };
+      let registered = true;
+      return {
+        ok: true,
+        value: () => {
+          if (!registered) return;
+          registered = false;
+          if (phaseCatalog[source] !== definition) return;
+          phaseCatalog = { ...phaseCatalog, [source]: [] };
+        },
+      };
+    },
+    startCapture() {
+      active = true;
+      latest = undefined;
+      return { ok: true, value: session };
+    },
+    activeCaptureId() {
+      return active ? captureId : undefined;
+    },
+    activeSession() {
+      return active ? session : undefined;
+    },
+    latestCapture() {
+      return latest;
+    },
+    get phaseCatalog() {
+      return phaseCatalog;
+    },
+  };
+}