@forgeax/engine-profiler 0.1.2

package/src/recorder.ts

@@ -0,0 +1,417 @@
+import type { ProfileClock } from './clock.js';
+import { boundaryError, type ProfilerResult, stateError } from './errors.js';
+import type {
+  ProfileCapture,
+  ProfilePhaseStart,
+  ProfileRecord,
+  ProfileSkipInput,
+  ProfileSource,
+} from './types.js';
+
+export interface RecorderLimits {
+  readonly frameLimit: number;
+  readonly eventLimit: number;
+  readonly detail?: ProfileDetail;
+}
+
+export type ProfileDetail = 'owner' | 'passes' | 'nested';
+
+export type RecorderPhaseCatalog = Readonly<Record<ProfileSource, readonly string[]>>;
+
+export interface RecorderSession {
+  readonly captureId: string;
+  readonly detail: ProfileDetail;
+  beginFrame(frameId: number): ProfilerResult<void>;
+  beginPhase(input: ProfilePhaseStart): ProfilerResult<void>;
+  beginPhase(source: ProfileSource, phase: string): ProfilerResult<void>;
+  endPhase(): ProfilerResult<void>;
+  recordSkip(input: ProfileSkipInput): ProfilerResult<void>;
+  endFrame(): ProfilerResult<void>;
+  finish(): ProfilerResult<ProfileCapture>;
+}
+
+const PHASE_RECORD_KIND = 1;
+const SKIP_RECORD_KIND = 2;
+
+interface RetainedRecordStore {
+  readonly kinds: Uint8Array;
+  readonly sources: ProfileSource[];
+  readonly phases: string[];
+  readonly frameIds: Float64Array;
+  readonly parentSources: Array<ProfileSource | undefined>;
+  readonly parentPhases: Array<string | undefined>;
+  readonly startMicros: Float64Array;
+  readonly endMicros: Float64Array;
+  readonly reasons: Array<string | undefined>;
+  count: number;
+}
+
+interface RecorderState {
+  readonly limits: RecorderLimits;
+  readonly phaseCatalog: RecorderPhaseCatalog;
+  readonly phaseArrays: Record<ProfileSource, readonly string[]>;
+  readonly phaseSets: Record<ProfileSource, ReadonlySet<string>>;
+  readonly recordStore: RetainedRecordStore;
+  readonly captureId: string;
+  readonly clock: ProfileClock;
+  readonly allocationReport: { profilerEventObjectAllocations: number } | undefined;
+  frameCount: number;
+  lastFrameId: number;
+  currentFrameId: number | undefined;
+  openSources: Array<ProfileSource | undefined>;
+  openPhaseNames: Array<string | undefined>;
+  openFrameIds: Array<number | undefined>;
+  openStartMicros: Array<number | undefined>;
+  openDepth: number;
+  droppedEventCount: number;
+  firstAffectedFrameId: number | undefined;
+  lastAffectedFrameId: number | undefined;
+  overflow: boolean;
+  finished: boolean;
+}
+
+const OK_VOID: ProfilerResult<void> = Object.freeze({ ok: true, value: undefined });
+
+function positiveSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+
+export function validateRecorderLimits(limits: RecorderLimits): ProfilerResult<void> {
+  if (!positiveSafeInteger(limits.frameLimit) || !positiveSafeInteger(limits.eventLimit)) {
+    return { ok: false, error: boundaryError(limits.frameLimit, limits.eventLimit) };
+  }
+  return OK_VOID;
+}
+
+function recordOverflow(state: RecorderState, frameId: number): void {
+  state.overflow = true;
+  state.droppedEventCount += 1;
+  state.firstAffectedFrameId ??= frameId;
+  state.lastAffectedFrameId = frameId;
+}
+
+function stateResult(state: RecorderState, operation: string): ProfilerResult<void> {
+  if (state.finished) return { ok: false, error: stateError(operation) };
+  return OK_VOID;
+}
+
+function sourceHasPhase(state: RecorderState, source: string, phase: string): boolean {
+  if (source !== 'app' && source !== 'render') return false;
+  const key = source;
+  const phases = state.phaseCatalog[key];
+  if (state.phaseArrays[key] !== phases) {
+    state.phaseArrays[key] = phases;
+    state.phaseSets[key] = new Set(phases);
+  }
+  return state.phaseSets[key].has(phase);
+}
+
+function sourceError(source: string, phase: string, frameId: number): ProfilerResult<never> {
+  return {
+    ok: false,
+    error: {
+      code: 'profile-source-failed',
+      expected: 'a phase declared by the source catalog',
+      hint: 'Use the source-owned phase catalog and retry the frame.',
+      detail: { source, phase, frameId },
+    },
+  };
+}
+
+function requireRetained<T>(value: T | undefined): T {
+  if (value === undefined) throw new Error('profiler record storage is incomplete');
+  return value;
+}
+
+function reserveRecord(state: RecorderState, frameId: number): number | undefined {
+  if (state.recordStore.count >= state.limits.eventLimit) {
+    recordOverflow(state, frameId);
+    return undefined;
+  }
+  const index = state.recordStore.count;
+  state.recordStore.count += 1;
+  return index;
+}
+
+function retainPhaseRecord(
+  state: RecorderState,
+  source: ProfileSource,
+  frameId: number,
+  phase: string,
+  parentSource: ProfileSource | undefined,
+  parentPhase: string | undefined,
+  startMicros: number,
+  endMicros: number,
+): void {
+  const index = reserveRecord(state, frameId);
+  if (index === undefined) return;
+  const records = state.recordStore;
+  records.kinds[index] = PHASE_RECORD_KIND;
+  records.sources[index] = source;
+  records.frameIds[index] = frameId;
+  records.phases[index] = phase;
+  records.parentSources[index] = parentSource;
+  records.parentPhases[index] = parentPhase;
+  records.startMicros[index] = startMicros;
+  records.endMicros[index] = endMicros;
+}
+
+function retainSkipRecord(
+  state: RecorderState,
+  source: ProfileSource,
+  frameId: number,
+  phase: string,
+  reason: string,
+): void {
+  const index = reserveRecord(state, frameId);
+  if (index === undefined) return;
+  const records = state.recordStore;
+  records.kinds[index] = SKIP_RECORD_KIND;
+  records.sources[index] = source;
+  records.frameIds[index] = frameId;
+  records.phases[index] = phase;
+  records.reasons[index] = reason;
+}
+
+function materializeRecords(state: RecorderState): ProfileRecord[] {
+  const retained = state.recordStore;
+  const records = new Array<ProfileRecord>(retained.count);
+  for (let index = 0; index < retained.count; index += 1) {
+    const kind = requireRetained(retained.kinds[index]);
+    const source = requireRetained(retained.sources[index]);
+    const frameId = requireRetained(retained.frameIds[index]);
+    const phase = requireRetained(retained.phases[index]);
+    if (kind === PHASE_RECORD_KIND) {
+      const parentSource = retained.parentSources[index];
+      const parentPhase = retained.parentPhases[index];
+      const startMicros = requireRetained(retained.startMicros[index]);
+      const endMicros = requireRetained(retained.endMicros[index]);
+      records[index] =
+        parentSource === undefined
+          ? {
+              kind: 'phase',
+              source,
+              frameId,
+              phase,
+              startMicros,
+              endMicros,
+              durationMicros: endMicros - startMicros,
+            }
+          : {
+              kind: 'phase',
+              source,
+              frameId,
+              phase,
+              parentSource,
+              parentPhase: requireRetained(parentPhase),
+              startMicros,
+              endMicros,
+              durationMicros: endMicros - startMicros,
+            };
+    } else {
+      records[index] = {
+        kind: 'skip',
+        source,
+        frameId,
+        phase,
+        reason: requireRetained(retained.reasons[index]),
+      };
+    }
+    if (state.allocationReport !== undefined) {
+      state.allocationReport.profilerEventObjectAllocations += 1;
+    }
+  }
+  return records;
+}
+
+function buildCapture(state: RecorderState): ProfileCapture {
+  const status = state.overflow
+    ? 'overflow'
+    : state.frameCount < state.limits.frameLimit || state.currentFrameId !== undefined
+      ? 'partial'
+      : 'complete';
+  const completeness = {
+    status,
+    retainedEventCount: state.recordStore.count,
+    droppedEventCount: state.droppedEventCount,
+    ...(status === 'partial' ? { incompleteReason: 'stopped-before-frame' } : {}),
+    ...(state.firstAffectedFrameId !== undefined
+      ? { firstAffectedFrameId: state.firstAffectedFrameId }
+      : {}),
+    ...(state.lastAffectedFrameId !== undefined
+      ? { lastAffectedFrameId: state.lastAffectedFrameId }
+      : {}),
+  } as ProfileCapture['completeness'];
+  return {
+    schemaVersion: '1.0',
+    captureId: state.captureId,
+    timeUnit: 'microseconds',
+    frameLimit: state.limits.frameLimit,
+    eventLimit: state.limits.eventLimit,
+    phaseCatalog: {
+      app: [...state.phaseCatalog.app],
+      render: [...state.phaseCatalog.render],
+    },
+    records: materializeRecords(state),
+    completeness,
+  };
+}
+
+export function createRecorder(
+  captureId: string,
+  limits: RecorderLimits,
+  clock: ProfileClock,
+  phaseCatalog: RecorderPhaseCatalog,
+  allocationReport?: { profilerEventObjectAllocations: number },
+): ProfilerResult<RecorderSession> {
+  const validLimits = validateRecorderLimits(limits);
+  if (!validLimits.ok) return validLimits;
+  const nowMicros = clock.nowMicros;
+  const state: RecorderState = {
+    limits,
+    phaseCatalog,
+    phaseArrays: {
+      app: phaseCatalog.app,
+      render: phaseCatalog.render,
+    },
+    phaseSets: {
+      app: new Set(phaseCatalog.app),
+      render: new Set(phaseCatalog.render),
+    },
+    recordStore: {
+      kinds: new Uint8Array(limits.eventLimit),
+      sources: new Array<ProfileSource>(limits.eventLimit),
+      phases: new Array<string>(limits.eventLimit),
+      frameIds: new Float64Array(limits.eventLimit),
+      parentSources: new Array<ProfileSource | undefined>(limits.eventLimit),
+      parentPhases: new Array<string | undefined>(limits.eventLimit),
+      startMicros: new Float64Array(limits.eventLimit),
+      endMicros: new Float64Array(limits.eventLimit),
+      reasons: new Array<string | undefined>(limits.eventLimit),
+      count: 0,
+    },
+    captureId,
+    clock,
+    allocationReport,
+    frameCount: 0,
+    lastFrameId: 0,
+    currentFrameId: undefined,
+    openSources: [],
+    openPhaseNames: [],
+    openFrameIds: [],
+    openStartMicros: [],
+    openDepth: 0,
+    droppedEventCount: 0,
+    firstAffectedFrameId: undefined,
+    lastAffectedFrameId: undefined,
+    overflow: false,
+    finished: false,
+  };
+
+  const session: RecorderSession = {
+    captureId,
+    detail: limits.detail ?? 'owner',
+    beginFrame(frameId) {
+      const stateCheck = stateResult(state, 'beginFrame');
+      if (!stateCheck.ok) return stateCheck;
+      if (
+        !positiveSafeInteger(frameId) ||
+        state.currentFrameId !== undefined ||
+        frameId <= state.lastFrameId
+      ) {
+        return { ok: false, error: stateError('beginFrame') };
+      }
+      state.lastFrameId = frameId;
+      state.currentFrameId = frameId;
+      state.frameCount += 1;
+      if (state.frameCount > state.limits.frameLimit)
+        recordOverflow(state, state.limits.frameLimit);
+      return OK_VOID;
+    },
+    beginPhase(inputOrSource: ProfilePhaseStart | ProfileSource, phaseName?: string) {
+      const stateCheck = stateResult(state, 'beginPhase');
+      if (!stateCheck.ok) return stateCheck;
+      const frameId = state.currentFrameId;
+      if (frameId === undefined) return { ok: false, error: stateError('beginPhase') };
+      const source = typeof inputOrSource === 'string' ? inputOrSource : inputOrSource.source;
+      const phase = typeof inputOrSource === 'string' ? phaseName : inputOrSource.phase;
+      if (phase === undefined) return { ok: false, error: stateError('beginPhase') };
+      if (!sourceHasPhase(state, source, phase)) return sourceError(source, phase, frameId);
+      const index = state.openDepth;
+      state.openSources[index] = source;
+      state.openPhaseNames[index] = phase;
+      state.openFrameIds[index] = frameId;
+      state.openStartMicros[index] = nowMicros();
+      state.openDepth += 1;
+      return OK_VOID;
+    },
+    endPhase() {
+      const stateCheck = stateResult(state, 'endPhase');
+      if (!stateCheck.ok) return stateCheck;
+      if (state.openDepth === 0) return { ok: false, error: stateError('endPhase') };
+      const index = state.openDepth - 1;
+      state.openDepth = index;
+      const source = state.openSources[index];
+      const phase = state.openPhaseNames[index];
+      const frameId = state.openFrameIds[index];
+      const startMicros = state.openStartMicros[index];
+      if (
+        source === undefined ||
+        phase === undefined ||
+        frameId === undefined ||
+        startMicros === undefined
+      ) {
+        return { ok: false, error: stateError('endPhase') };
+      }
+      const parentIndex = index - 1;
+      const parentSource = parentIndex >= 0 ? state.openSources[parentIndex] : undefined;
+      const parentPhase = parentIndex >= 0 ? state.openPhaseNames[parentIndex] : undefined;
+      if (!state.overflow) {
+        const endMicros = Math.max(startMicros, nowMicros());
+        retainPhaseRecord(
+          state,
+          source,
+          frameId,
+          phase,
+          parentSource,
+          parentPhase,
+          startMicros,
+          endMicros,
+        );
+      } else {
+        recordOverflow(state, frameId);
+      }
+      return OK_VOID;
+    },
+    recordSkip(input) {
+      const stateCheck = stateResult(state, 'recordSkip');
+      if (!stateCheck.ok) return stateCheck;
+      const frameId = state.currentFrameId;
+      if (frameId === undefined || state.openDepth > 0)
+        return { ok: false, error: stateError('recordSkip') };
+      if (!sourceHasPhase(state, input.source, input.phase))
+        return sourceError(input.source, input.phase, frameId);
+      if (state.overflow) recordOverflow(state, frameId);
+      else retainSkipRecord(state, input.source, frameId, input.phase, input.reason);
+      return OK_VOID;
+    },
+    endFrame() {
+      const stateCheck = stateResult(state, 'endFrame');
+      if (!stateCheck.ok) return stateCheck;
+      if (state.currentFrameId === undefined || state.openDepth > 0)
+        return { ok: false, error: stateError('endFrame') };
+      state.currentFrameId = undefined;
+      return OK_VOID;
+    },
+    finish() {
+      const stateCheck = stateResult(state, 'finish');
+      if (!stateCheck.ok) return { ok: false, error: stateCheck.error };
+      if (state.openDepth > 0 || state.currentFrameId !== undefined) {
+        return { ok: false, error: stateError('finish') };
+      }
+      state.finished = true;
+      return { ok: true, value: buildCapture(state) };
+    },
+  };
+  return { ok: true, value: session };
+}

package/src/schema.ts

@@ -0,0 +1,168 @@
+// Ajv ships this entry as CommonJS. Use the named constructor so Vite's
+// native ESM dev server does not assume a synthetic default export when the
+// profiler is imported by the browser runtime.
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import schemaDocument from '../schema/profile-capture.schema.json' with { type: 'json' };
+import type { ProfileCapture, ProfileRecord } from './generated/profile-capture.js';
+import type { ProfileResult } from './types.js';
+
+export type ProfileArtifactError = {
+  readonly code: 'profile-artifact-invalid' | 'profile-artifact-incompatible';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly path: string; readonly message: string };
+};
+
+const validator = new Ajv2020({ allErrors: true, strict: true }).compile(schemaDocument);
+
+function error(
+  code: ProfileArtifactError['code'],
+  path: string,
+  message: string,
+): ProfileResult<never, ProfileArtifactError> {
+  return {
+    ok: false,
+    error: {
+      code,
+      expected: 'a schema-valid ProfileCapture v1 artifact',
+      hint: 'Regenerate or select a compatible ProfileCapture artifact before retrying.',
+      detail: { path, message },
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function validateSemanticRules(
+  value: Record<string, unknown>,
+): ProfileResult<ProfileCapture, ProfileArtifactError> {
+  const catalog = value.phaseCatalog as { app: string[]; render: string[] };
+  const records = value.records as ProfileRecord[];
+  let previousFrameId = 0;
+
+  for (const [index, record] of records.entries()) {
+    if (record.frameId < previousFrameId) {
+      return error(
+        'profile-artifact-invalid',
+        `/records/${index}/frameId`,
+        'frameId must not decrease',
+      );
+    }
+    previousFrameId = record.frameId;
+    if (!catalog[record.source].includes(record.phase)) {
+      return error(
+        'profile-artifact-invalid',
+        `/records/${index}/phase`,
+        'phase is absent from its source catalog',
+      );
+    }
+    if (record.kind === 'phase' && record.parentPhase !== undefined) {
+      const parentCatalog = catalog[record.parentSource ?? record.source];
+      if (!parentCatalog.includes(record.parentPhase)) {
+        return error(
+          'profile-artifact-invalid',
+          `/records/${index}/parentPhase`,
+          'parentPhase is absent from its source catalog',
+        );
+      }
+      if (record.parentPhase === record.phase) {
+        return error(
+          'profile-artifact-invalid',
+          `/records/${index}/parentPhase`,
+          'parentPhase must differ from phase',
+        );
+      }
+    } else if (record.kind === 'phase' && record.parentSource !== undefined) {
+      return error(
+        'profile-artifact-invalid',
+        `/records/${index}/parentSource`,
+        'parentSource requires parentPhase',
+      );
+    }
+    if (record.kind === 'phase') {
+      if (record.endMicros < record.startMicros) {
+        return error(
+          'profile-artifact-invalid',
+          `/records/${index}/endMicros`,
+          'endMicros must not precede startMicros',
+        );
+      }
+      if (record.durationMicros !== record.endMicros - record.startMicros) {
+        return error(
+          'profile-artifact-invalid',
+          `/records/${index}/durationMicros`,
+          'durationMicros must equal endMicros - startMicros',
+        );
+      }
+    }
+  }
+
+  const completeness = value.completeness as ProfileCapture['completeness'];
+  if (completeness.retainedEventCount !== records.length) {
+    return error(
+      'profile-artifact-invalid',
+      '/completeness/retainedEventCount',
+      'retainedEventCount must equal records.length',
+    );
+  }
+  if (completeness.status === 'complete') {
+    if (completeness.incompleteReason !== undefined || completeness.droppedEventCount !== 0) {
+      return error(
+        'profile-artifact-invalid',
+        '/completeness',
+        'complete captures cannot contain incomplete evidence',
+      );
+    }
+  }
+  if (completeness.status === 'partial' && completeness.incompleteReason === undefined) {
+    return error(
+      'profile-artifact-invalid',
+      '/completeness/incompleteReason',
+      'partial captures require incompleteReason',
+    );
+  }
+  if (completeness.status === 'overflow') {
+    if (completeness.droppedEventCount === 0) {
+      return error(
+        'profile-artifact-invalid',
+        '/completeness/droppedEventCount',
+        'overflow captures require dropped events',
+      );
+    }
+    if (
+      completeness.firstAffectedFrameId === undefined ||
+      completeness.lastAffectedFrameId === undefined
+    ) {
+      return error(
+        'profile-artifact-invalid',
+        '/completeness',
+        'overflow captures require affected frame bounds',
+      );
+    }
+  }
+  return { ok: true, value: value as unknown as ProfileCapture };
+}
+
+export function validateProfileCapture(
+  value: unknown,
+): ProfileResult<ProfileCapture, ProfileArtifactError> {
+  if (!isRecord(value)) return error('profile-artifact-invalid', '', 'artifact must be an object');
+  if (value.schemaVersion !== '1.0') {
+    return error(
+      'profile-artifact-incompatible',
+      '/schemaVersion',
+      'reader supports schema version 1.0 only',
+    );
+  }
+  if (!validator(value)) {
+    const issue = validator.errors?.[0];
+    return error(
+      'profile-artifact-invalid',
+      issue?.instancePath ?? '',
+      issue?.message ?? 'schema validation failed',
+    );
+  }
+  return validateSemanticRules(value);
+}

package/src/tool-preview-profile.ts

@@ -0,0 +1,67 @@
+import { type ProfileCapture, validateProfileCapture } from './index.js';
+
+export interface ToolPreviewProfileRef {
+  readonly kind: 'profile-capture';
+  readonly digest: string;
+  readonly uri: string;
+}
+
+export interface ToolPreviewProfileManifest {
+  readonly runId: string;
+  readonly captureId: string;
+  readonly profileDigest: string;
+}
+
+export type ToolPreviewProfileResult =
+  | {
+      readonly ok: true;
+      readonly value: {
+        readonly runId: string;
+        readonly captureId: string;
+        readonly profile: ProfileCapture;
+      };
+    }
+  | {
+      readonly ok: false;
+      readonly error: {
+        readonly code: string;
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: unknown;
+      };
+    };
+
+export function consumeToolPreviewProfile(input: {
+  readonly manifest: ToolPreviewProfileManifest;
+  readonly profile: unknown;
+  readonly ref: ToolPreviewProfileRef;
+}): ToolPreviewProfileResult {
+  if (input.ref.digest !== input.manifest.profileDigest) {
+    return fail('profile digest matches manifest identity');
+  }
+  const profileResult = validateProfileCapture(input.profile);
+  if (!profileResult.ok) return fail(profileResult.error.expected);
+  if (profileResult.value.captureId !== input.manifest.captureId) {
+    return fail('ProfileCapture.captureId matches manifest captureId');
+  }
+  return {
+    ok: true,
+    value: {
+      runId: input.manifest.runId,
+      captureId: input.manifest.captureId,
+      profile: profileResult.value,
+    },
+  };
+}
+
+function fail(expected: string): Extract<ToolPreviewProfileResult, { readonly ok: false }> {
+  return {
+    ok: false,
+    error: {
+      code: 'tool-preview-profile-mismatch',
+      expected,
+      hint: 'read the ProfileCapture through its owner schema and regenerate the manifest join',
+      detail: { expected },
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,56 @@
+import type {
+  ProfileCapture,
+  ProfileCompleteness,
+  ProfilePhaseRecord,
+  ProfileRecord,
+  ProfileSkipRecord,
+  ProfileSource,
+} from './generated/profile-capture.js';
+
+export type {
+  ProfileCapture,
+  ProfileCompleteness,
+  ProfilePhaseRecord,
+  ProfileRecord,
+  ProfileSkipRecord,
+  ProfileSource,
+};
+
+export type ProfileResult<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+export type ProfileSinkFailure = {
+  readonly code: string;
+  readonly expected?: string;
+  readonly hint?: string;
+  readonly detail?: { readonly message?: string };
+};
+
+export type ProfileSinkWriteResult =
+  | { readonly ok: true; readonly value?: undefined }
+  | { readonly ok: false; readonly error: ProfileSinkFailure };
+
+export interface ProfileSink {
+  write(capture: ProfileCapture): void | ProfileSinkWriteResult;
+}
+
+export interface ProfileAllocationReport {
+  profilerEventObjectAllocations: number;
+}
+
+export interface ProfileFrameToken {
+  readonly captureId: string;
+  readonly frameId: number;
+}
+
+export interface ProfilePhaseStart {
+  readonly source: ProfileSource;
+  readonly phase: string;
+}
+
+export interface ProfileSkipInput {
+  readonly source: ProfileSource;
+  readonly phase: string;
+  readonly reason: string;
+}