@forgeax/engine-profiler 0.1.2

package/src/generated/profile-capture.ts

@@ -0,0 +1,48 @@
+// Generated by scripts/generate-profile-types.mjs. Do not edit.
+// Schema version: 1.0
+
+export type ProfileSource = 'app' | 'render';
+export type ProfileRecordKind = 'phase' | 'skip';
+export type ProfileCompletenessStatus = 'complete' | 'partial' | 'overflow';
+
+export interface ProfilePhaseRecord {
+  readonly kind: 'phase';
+  readonly source: ProfileSource;
+  readonly frameId: number;
+  readonly phase: string;
+  readonly parentSource?: ProfileSource;
+  readonly parentPhase?: string;
+  readonly startMicros: number;
+  readonly endMicros: number;
+  readonly durationMicros: number;
+}
+
+export interface ProfileSkipRecord {
+  readonly kind: 'skip';
+  readonly source: ProfileSource;
+  readonly frameId: number;
+  readonly phase: string;
+  readonly reason: string;
+}
+
+export type ProfileRecord = ProfilePhaseRecord | ProfileSkipRecord;
+
+export interface ProfileCompleteness {
+  readonly status: ProfileCompletenessStatus;
+  readonly retainedEventCount: number;
+  readonly droppedEventCount: number;
+  readonly incompleteReason?: string;
+  readonly firstAffectedFrameId?: number;
+  readonly lastAffectedFrameId?: number;
+}
+
+export interface ProfileCapture {
+  readonly schemaVersion: '1.0';
+  readonly captureId: string;
+  readonly timeUnit: 'microseconds';
+  readonly frameLimit: number;
+  readonly eventLimit: number;
+  readonly phaseCatalog: Readonly<{ app: readonly string[]; render: readonly string[] }>;
+  readonly records: readonly ProfileRecord[];
+  readonly completeness: ProfileCompleteness;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/** Creates the default monotonic microsecond clock. */
+
+/** Opt-in browser User Timing projection shared by editor and Play hosts. */
+export {
+  createUserTimingProfiler,
+  type UserTimingProfilerOptions,
+} from './browser-user-timing.js';
+export { createProfileClock } from './clock.js';
+export type {
+  ProfileComparisonError,
+  ProfileComparisonPhaseDelta,
+  ProfileComparisonPhaseFact,
+  ProfileComparisonPhaseIdentity,
+  ProfileComparisonPhaseRow,
+  ProfileComparisonProjection,
+  ProfileComparisonSide,
+} from './compare.js';
+/** Compares two validated captures without adding policy or mutating either input. */
+export { compareProfileCaptures } from './compare.js';
+/** Structured expected-failure vocabulary for profiler operations. */
+export type { ProfilerError, ProfilerErrorCode } from './errors.js';
+export type {
+  ProfileFrameModel,
+  ProfileModel,
+  ProfilePhaseModel,
+  ProfileSummaryModel,
+} from './model.js';
+/** Projects a validated capture into offline frame and phase summaries. */
+export { buildProfileModel } from './model.js';
+/** Bounded CPU profiler capability; it is inert until a host passes it to App or Render. */
+export type { Profiler } from './profiler.js';
+/** Creates an opt-in bounded profiler with optional sink and allocation evidence. */
+export { createProfiler } from './profiler.js';
+export type { ProfileDetail, RecorderSession } from './recorder.js';
+/** Validates a persisted capture before model building or CLI-style analysis. */
+export { validateProfileCapture } from './schema.js';
+export {
+  consumeToolPreviewProfile,
+  type ToolPreviewProfileManifest,
+  type ToolPreviewProfileRef,
+  type ToolPreviewProfileResult,
+} from './tool-preview-profile.js';
+export type {
+  ProfileAllocationReport,
+  ProfileCapture,
+  ProfileCompleteness,
+  ProfileFrameToken,
+  ProfilePhaseRecord,
+  ProfileRecord,
+  ProfileResult,
+  ProfileSink,
+  ProfileSkipRecord,
+  ProfileSource,
+} from './types.js';

package/src/model.ts

@@ -0,0 +1,161 @@
+import { type ProfileArtifactError, validateProfileCapture } from './schema.js';
+import type { ProfileCapture, ProfilePhaseRecord, ProfileRecord, ProfileResult } from './types.js';
+
+export interface ProfileFrameModel {
+  readonly frameId: number;
+  readonly recordCount: number;
+  readonly phaseCount: number;
+  readonly skipCount: number;
+  readonly durationMicros: number;
+  readonly records: readonly ProfileRecord[];
+}
+
+export interface ProfilePhaseModel {
+  readonly source: ProfilePhaseRecord['source'];
+  readonly phase: string;
+  readonly parentSource?: ProfilePhaseRecord['source'];
+  readonly parentPhase?: string;
+  readonly count: number;
+  readonly skipCount: number;
+  readonly p95DurationMicros: number | null;
+}
+
+export interface ProfileSummaryModel {
+  readonly schemaVersion: ProfileCapture['schemaVersion'];
+  readonly captureId: string;
+  readonly timeUnit: ProfileCapture['timeUnit'];
+  readonly frameLimit: number;
+  readonly eventLimit: number;
+  readonly completeness: ProfileCapture['completeness'];
+  readonly frameRange: { readonly first: number; readonly last: number } | null;
+  readonly frameCount: number;
+  readonly recordCount: number;
+  readonly phaseCount: number;
+  readonly skipCount: number;
+  readonly p95DurationMicros: number | null;
+}
+
+export interface ProfileModel {
+  readonly summary: ProfileSummaryModel;
+  readonly completeness: ProfileCapture['completeness'];
+  readonly frames: readonly ProfileFrameModel[];
+  readonly phases: readonly ProfilePhaseModel[];
+}
+
+function nearestRankP95(values: readonly number[]): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((left, right) => left - right);
+  return sorted[Math.ceil(sorted.length * 0.95) - 1] ?? null;
+}
+
+function cloneRecord(record: ProfileRecord): ProfileRecord {
+  return { ...record };
+}
+
+function isRootPhase(record: ProfileRecord): record is ProfilePhaseRecord {
+  return record.kind === 'phase' && record.parentPhase === undefined;
+}
+
+function buildFrames(records: readonly ProfileRecord[]): ProfileFrameModel[] {
+  const frameMap = new Map<number, ProfileRecord[]>();
+  for (const record of records) {
+    const frameRecords = frameMap.get(record.frameId);
+    if (frameRecords === undefined) frameMap.set(record.frameId, [cloneRecord(record)]);
+    else frameRecords.push(cloneRecord(record));
+  }
+  return [...frameMap.entries()].map(([frameId, frameRecords]) => ({
+    frameId,
+    recordCount: frameRecords.length,
+    phaseCount: frameRecords.filter((record) => record.kind === 'phase').length,
+    skipCount: frameRecords.filter((record) => record.kind === 'skip').length,
+    durationMicros: frameRecords.reduce(
+      (total, record) => total + (isRootPhase(record) ? record.durationMicros : 0),
+      0,
+    ),
+    records: frameRecords,
+  }));
+}
+
+function buildPhases(records: readonly ProfileRecord[]): ProfilePhaseModel[] {
+  const phaseMap = new Map<
+    string,
+    {
+      source: ProfilePhaseRecord['source'];
+      phase: string;
+      parentSource: ProfilePhaseRecord['source'] | undefined;
+      parentPhase: string | undefined;
+      durations: number[];
+      skipCount: number;
+    }
+  >();
+  for (const record of records) {
+    const parentSource = record.kind === 'phase' ? record.parentSource : undefined;
+    const parentPhase = record.kind === 'phase' ? record.parentPhase : undefined;
+    const key = `${record.source}:${parentSource ?? ''}:${parentPhase ?? ''}:${record.phase}`;
+    let entry = phaseMap.get(key);
+    if (entry === undefined) {
+      entry = {
+        source: record.source,
+        phase: record.phase,
+        parentSource,
+        parentPhase,
+        durations: [],
+        skipCount: 0,
+      };
+      phaseMap.set(key, entry);
+    }
+    if (record.kind === 'phase') entry.durations.push(record.durationMicros);
+    else entry.skipCount += 1;
+  }
+  return [...phaseMap.values()].map(
+    ({ source, phase, parentSource, parentPhase, durations, skipCount }) => ({
+      source,
+      phase,
+      ...(parentSource === undefined ? {} : { parentSource }),
+      ...(parentPhase === undefined ? {} : { parentPhase }),
+      count: durations.length,
+      skipCount,
+      p95DurationMicros: nearestRankP95(durations),
+    }),
+  );
+}
+
+export function buildProfileModel(
+  value: unknown,
+): ProfileResult<ProfileModel, ProfileArtifactError> {
+  const validated = validateProfileCapture(value);
+  if (!validated.ok) return validated;
+  const capture = validated.value;
+  const frames = buildFrames(capture.records);
+  const phases = buildPhases(capture.records);
+  const durations = capture.records.filter(isRootPhase).map((record) => record.durationMicros);
+  const completeness = { ...capture.completeness };
+  const phaseCount = capture.records.filter((record) => record.kind === 'phase').length;
+  const skipCount = capture.records.length - phaseCount;
+  const frameRange =
+    frames.length === 0
+      ? null
+      : { first: frames[0]?.frameId as number, last: frames[frames.length - 1]?.frameId as number };
+  return {
+    ok: true,
+    value: {
+      summary: {
+        schemaVersion: capture.schemaVersion,
+        captureId: capture.captureId,
+        timeUnit: capture.timeUnit,
+        frameLimit: capture.frameLimit,
+        eventLimit: capture.eventLimit,
+        completeness,
+        frameRange,
+        frameCount: frames.length,
+        recordCount: capture.records.length,
+        phaseCount,
+        skipCount,
+        p95DurationMicros: nearestRankP95(durations),
+      },
+      completeness,
+      frames,
+      phases,
+    },
+  };
+}

package/src/profiler.ts

@@ -0,0 +1,201 @@
+import { createProfileClock, type ProfileClock } from './clock.js';
+import type { ProfilerError, ProfilerResult } from './errors.js';
+import type { RecorderPhaseCatalog } from './recorder.js';
+import { createRecorder, type RecorderLimits, type RecorderSession } from './recorder.js';
+import type { ProfileAllocationReport, ProfileCapture, ProfileSink } from './types.js';
+
+export interface ProfilerOptions {
+  readonly clock?: ProfileClock;
+  readonly sink?: ProfileSink;
+  readonly enabled?: boolean;
+  readonly phaseCatalog?: RecorderPhaseCatalog;
+  readonly allocationReport?: ProfileAllocationReport;
+}
+
+export type ProfilerCatalogSource = keyof RecorderPhaseCatalog;
+
+export interface Profiler {
+  registerPhaseCatalog(
+    source: ProfilerCatalogSource,
+    phases: readonly string[],
+  ): ProfilerResult<() => void>;
+  startCapture(limits: RecorderLimits): ProfilerResult<RecorderSession>;
+  activeCaptureId(): string | undefined;
+  activeSession(): RecorderSession | undefined;
+  latestCapture(): ProfileCapture | undefined;
+  readonly phaseCatalog: RecorderPhaseCatalog;
+}
+
+export function createProfiler(options: ProfilerOptions = {}): Profiler {
+  const clock = options.clock ?? createProfileClock();
+  const enabled = options.enabled ?? true;
+  const sink = options.sink;
+  const phaseCatalog: RecorderPhaseCatalog =
+    options.phaseCatalog === undefined
+      ? { app: [], render: [] }
+      : { app: [...options.phaseCatalog.app], render: [...options.phaseCatalog.render] };
+  const registeredSources = new Set<ProfilerCatalogSource>();
+  if (options.phaseCatalog !== undefined) {
+    registeredSources.add('app');
+    registeredSources.add('render');
+  }
+  let nextCaptureNumber = 1;
+  let active: RecorderSession | undefined;
+  let latest: ProfileCapture | undefined;
+
+  return {
+    registerPhaseCatalog(source, phases) {
+      if (registeredSources.has(source)) {
+        return {
+          ok: false,
+          error: {
+            code: 'phase-catalog-conflict',
+            expected: `one ${source} phase catalog definition`,
+            hint: 'Use the owner declaration already registered on this profiler.',
+            detail: {
+              source,
+              expected: [...phaseCatalog[source]],
+              actual: [...phases],
+            },
+          },
+        };
+      }
+      const definition = [...phases];
+      Object.assign(phaseCatalog, { [source]: definition });
+      registeredSources.add(source);
+      let active = true;
+      return {
+        ok: true,
+        value: () => {
+          if (!active) return;
+          active = false;
+          if (phaseCatalog[source] !== definition) return;
+          Object.assign(phaseCatalog, { [source]: [] });
+          registeredSources.delete(source);
+        },
+      };
+    },
+    startCapture(limits) {
+      if (!enabled) {
+        return {
+          ok: false,
+          error: {
+            code: 'profiler-not-enabled',
+            expected: 'an explicitly enabled profiler',
+            hint: 'Enable the development profiler capability before starting capture.',
+            detail: { enabled: false },
+          },
+        };
+      }
+      if (active !== undefined) {
+        return {
+          ok: false,
+          error: {
+            code: 'capture-already-active',
+            expected: 'no active capture',
+            hint: 'Finish or stop the active capture before starting another one.',
+            detail: { captureId: active.captureId },
+          },
+        };
+      }
+      const captureId = `capture-${String(nextCaptureNumber).padStart(4, '0')}`;
+      nextCaptureNumber += 1;
+      const result = createRecorder(
+        captureId,
+        limits,
+        clock,
+        phaseCatalog,
+        options.allocationReport,
+      );
+      if (!result.ok) return result;
+      const session = wrapSink(result.value, sink, limits.frameLimit, (capture) => {
+        latest = capture;
+        active = undefined;
+      });
+      active = session;
+      return { ok: true, value: session };
+    },
+    activeCaptureId() {
+      return active?.captureId;
+    },
+    activeSession() {
+      return active;
+    },
+    latestCapture() {
+      return latest;
+    },
+    get phaseCatalog() {
+      return phaseCatalog;
+    },
+  };
+}
+
+function wrapSink(
+  session: RecorderSession,
+  sink: ProfileSink | undefined,
+  frameLimit: number,
+  complete: (capture: ProfileCapture) => void,
+): RecorderSession {
+  let frameCount = 0;
+  let terminal: ProfilerResult<ProfileCapture> | undefined;
+
+  function finish(): ProfilerResult<ProfileCapture> {
+    if (terminal !== undefined) return terminal;
+    const result = session.finish();
+    if (!result.ok) return result;
+    complete(result.value);
+    if (sink === undefined) {
+      terminal = result;
+      return result;
+    }
+    try {
+      const sinkResult = sink.write(result.value);
+      if (sinkResult !== undefined && !sinkResult.ok) {
+        terminal = {
+          ok: false,
+          error: {
+            code: 'profile-sink-failed',
+            expected: 'a sink that accepts a partial or complete artifact',
+            hint: 'Replace the sink or retain the returned partial artifact for offline retry.',
+            detail: { message: sinkResult.error.detail?.message ?? 'sink rejected artifact' },
+          },
+        };
+        return terminal;
+      }
+      terminal = result;
+      return result;
+    } catch (caught) {
+      terminal = {
+        ok: false,
+        error: {
+          code: 'profile-sink-failed',
+          expected: 'a sink that accepts a partial or complete artifact',
+          hint: 'Replace the sink or retain the returned partial artifact for offline retry.',
+          detail: {
+            message: caught instanceof Error ? caught.message : 'sink threw a non-Error value',
+          },
+        },
+      };
+      return terminal;
+    }
+  }
+
+  return {
+    ...session,
+    beginFrame(frameId) {
+      const result = session.beginFrame(frameId);
+      if (result.ok) frameCount += 1;
+      return result;
+    },
+    endFrame() {
+      const result = session.endFrame();
+      if (result.ok && frameCount >= frameLimit) finish();
+      return result;
+    },
+    finish() {
+      return finish();
+    },
+  };
+}
+
+export type { ProfileCapture, ProfilerError };