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

package/dist/model.d.ts

@@ -0,0 +1,44 @@
+import { type ProfileArtifactError } 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[];
+}
+export declare function buildProfileModel(value: unknown): ProfileResult<ProfileModel, ProfileArtifactError>;
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAA0B,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;IACtD,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC/C;AAgFD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,GACb,aAAa,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAoCnD"}

package/dist/profiler.d.ts

@@ -0,0 +1,24 @@
+import { type ProfileClock } from './clock.js';
+import type { ProfilerError, ProfilerResult } from './errors.js';
+import type { RecorderPhaseCatalog } from './recorder.js';
+import { 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 declare function createProfiler(options?: ProfilerOptions): Profiler;
+export type { ProfileCapture, ProfilerError };
+//# sourceMappingURL=profiler.d.ts.map

package/dist/profiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiler.d.ts","sourceRoot":"","sources":["../src/profiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAkB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;CACrD;AAED,MAAM,MAAM,qBAAqB,GAAG,MAAM,oBAAoB,CAAC;AAE/D,MAAM,WAAW,QAAQ;IACvB,oBAAoB,CAClB,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,cAAc,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9B,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IACtE,eAAe,IAAI,MAAM,GAAG,SAAS,CAAC;IACtC,aAAa,IAAI,eAAe,GAAG,SAAS,CAAC;IAC7C,aAAa,IAAI,cAAc,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;CAC7C;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAsGtE;AAsED,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC"}

package/dist/recorder.d.ts

@@ -0,0 +1,26 @@
+import type { ProfileClock } from './clock.js';
+import { type ProfilerResult } from './errors.js';
+import type { ProfileCapture, ProfilePhaseStart, 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>;
+}
+export declare function validateRecorderLimits(limits: RecorderLimits): ProfilerResult<void>;
+export declare function createRecorder(captureId: string, limits: RecorderLimits, clock: ProfileClock, phaseCatalog: RecorderPhaseCatalog, allocationReport?: {
+    profilerEventObjectAllocations: number;
+}): ProfilerResult<RecorderSession>;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAiB,KAAK,cAAc,EAAc,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAEjB,gBAAgB,EAChB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAEtF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC3D,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACvE,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IACjC,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,IAAI,cAAc,CAAC,cAAc,CAAC,CAAC;CAC1C;AAgDD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAAC,IAAI,CAAC,CAKnF;AAgLD,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,oBAAoB,EAClC,gBAAgB,CAAC,EAAE;IAAE,8BAA8B,EAAE,MAAM,CAAA;CAAE,GAC5D,cAAc,CAAC,eAAe,CAAC,CAsJjC"}

package/dist/schema.d.ts

@@ -0,0 +1,13 @@
+import type { ProfileCapture } 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;
+    };
+};
+export declare function validateProfileCapture(value: unknown): ProfileResult<ProfileCapture, ProfileArtifactError>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,gCAAgC,CAAC;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,IAAI,EAAE,0BAA0B,GAAG,+BAA+B,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE,CAAC;AAsIF,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,aAAa,CAAC,cAAc,EAAE,oBAAoB,CAAC,CAkBrD"}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACd,MAAM,gCAAgC,CAAC;AAExC,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,aAAa,GACd,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,IAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE9C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,sBAAsB,CAAC;CAC/D;AAED,MAAM,WAAW,uBAAuB;IACtC,8BAA8B,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@forgeax/engine-profiler",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "CPU profile capture, bounded recording, and deterministic offline analysis for forgeax-engine.",
+  "bin": {
+    "forgeax-engine-profiler": "./bin/forgeax-engine-profiler.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.mjs"
+    },
+    "./browser-user-timing": {
+      "types": "./dist/browser-user-timing.d.ts",
+      "import": "./dist/browser-user-timing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "bin",
+    "dist",
+    "schema",
+    "src",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library package without a canvas frame loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "performance gate runs through the package test:perf script"
+      },
+      "gate": {
+        "enabled": true,
+        "command": "pnpm --filter @forgeax/engine-profiler test:perf"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "cli": "node bin/forgeax-engine-profiler.mjs",
+    "test": "vitest run",
+    "smoke:consumer": "node scripts/consume-smoke.mjs",
+    "test:perf": "node ../../scripts/bench/profiler-overhead.mjs"
+  }
+}

package/schema/profile-capture.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgeax.dev/schemas/profile-capture-1.0.json",
+  "title": "ForgeaX ProfileCapture",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "captureId", "timeUnit", "frameLimit", "eventLimit", "phaseCatalog", "records", "completeness"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "captureId": { "type": "string", "pattern": "^capture-[0-9]{4,}$" },
+    "timeUnit": { "const": "microseconds" },
+    "frameLimit": { "$ref": "#/$defs/positiveSafeInteger" },
+    "eventLimit": { "$ref": "#/$defs/positiveSafeInteger" },
+    "phaseCatalog": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["app", "render"],
+      "properties": { "app": { "$ref": "#/$defs/phaseNames" }, "render": { "$ref": "#/$defs/phaseNames" } }
+    },
+    "records": { "type": "array", "items": { "$ref": "#/$defs/record" } },
+    "completeness": { "$ref": "#/$defs/completeness" }
+  },
+  "$defs": {
+    "positiveSafeInteger": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+    "nonNegativeSafeInteger": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+    "phaseNames": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "source": { "enum": ["app", "render"] },
+    "phaseRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "source", "frameId", "phase", "startMicros", "endMicros", "durationMicros"],
+      "properties": {
+        "kind": { "const": "phase" },
+        "source": { "$ref": "#/$defs/source" },
+        "frameId": { "$ref": "#/$defs/positiveSafeInteger" },
+        "phase": { "type": "string", "minLength": 1 },
+        "parentSource": { "$ref": "#/$defs/source" },
+        "parentPhase": { "type": "string", "minLength": 1 },
+        "startMicros": { "$ref": "#/$defs/nonNegativeSafeInteger" },
+        "endMicros": { "$ref": "#/$defs/nonNegativeSafeInteger" },
+        "durationMicros": { "$ref": "#/$defs/nonNegativeSafeInteger" }
+      }
+    },
+    "skipRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "source", "frameId", "phase", "reason"],
+      "properties": {
+        "kind": { "const": "skip" },
+        "source": { "$ref": "#/$defs/source" },
+        "frameId": { "$ref": "#/$defs/positiveSafeInteger" },
+        "phase": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "record": { "oneOf": [{ "$ref": "#/$defs/phaseRecord" }, { "$ref": "#/$defs/skipRecord" }] },
+    "completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "retainedEventCount", "droppedEventCount"],
+      "properties": {
+        "status": { "enum": ["complete", "partial", "overflow"] },
+        "retainedEventCount": { "$ref": "#/$defs/nonNegativeSafeInteger" },
+        "droppedEventCount": { "$ref": "#/$defs/nonNegativeSafeInteger" },
+        "incompleteReason": { "type": "string", "minLength": 1 },
+        "firstAffectedFrameId": { "$ref": "#/$defs/positiveSafeInteger" },
+        "lastAffectedFrameId": { "$ref": "#/$defs/positiveSafeInteger" }
+      }
+    }
+  }
+}

package/scripts/consume-smoke.mjs

@@ -0,0 +1,17 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const cliPath = fileURLToPath(new URL('../dist/cli.mjs', import.meta.url));
+const fixturePath = fileURLToPath(
+  new URL('../src/__tests__/fixtures/profile-capture/model-input.json', import.meta.url),
+);
+const result = spawnSync(process.execPath, [cliPath, 'summary', '--file', fixturePath], {
+  encoding: 'utf8',
+});
+
+if (result.status !== 0) {
+  process.stderr.write(result.stderr);
+  process.exitCode = result.status ?? 1;
+} else {
+  process.stdout.write(result.stdout);
+}

package/scripts/generate-profile-types.mjs

@@ -0,0 +1,66 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const packageRoot = new URL('../', import.meta.url);
+const schemaPath = new URL('./schema/profile-capture.schema.json', packageRoot);
+const outputPath = new URL('./src/generated/profile-capture.ts', packageRoot);
+const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+
+const output = `// Generated by scripts/generate-profile-types.mjs. Do not edit.
+// Schema version: ${schema.properties.schemaVersion.const}
+
+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;
+}
+`;
+
+if (process.argv.includes('--check')) {
+  const current = readFileSync(outputPath, 'utf8');
+  if (current !== output) {
+    process.stderr.write(`${outputPath.pathname} is stale\n`);
+    process.exitCode = 1;
+  }
+} else {
+  writeFileSync(outputPath, output);
+}

package/src/__tests__/cli-consumer.integration.test.ts

@@ -0,0 +1,113 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+const cliPath = fileURLToPath(new URL('../../dist/cli.mjs', import.meta.url));
+const smokePath = fileURLToPath(new URL('../../scripts/consume-smoke.mjs', import.meta.url));
+const fixtureRoot = new URL('./fixtures/cli/', import.meta.url);
+
+function runCli(args: readonly string[], input = '') {
+  return spawnSync(process.execPath, [cliPath, ...args], {
+    cwd: packageRoot,
+    input,
+    encoding: 'utf8',
+  });
+}
+
+function readFixture(name: string): string {
+  return readFileSync(fileURLToPath(new URL(name, fixtureRoot)), 'utf8');
+}
+
+function runSummaryForFixture(name: string) {
+  const fixturePath = fileURLToPath(new URL(name, fixtureRoot));
+  return runCli(['summary', '--file', fixturePath]);
+}
+
+function parseObject(output: string): Record<string, unknown> {
+  return JSON.parse(output) as Record<string, unknown>;
+}
+
+describe('profiler CLI consumer smoke', () => {
+  it('preserves completeness states through the built public CLI', () => {
+    const complete = runSummaryForFixture('valid-capture.json');
+    const partial = runSummaryForFixture('partial-capture.json');
+    const overflow = runSummaryForFixture('../profile-capture/valid-overflow.json');
+    const empty = runCli(
+      ['summary'],
+      JSON.stringify({
+        schemaVersion: '1.0',
+        captureId: 'capture-0044',
+        timeUnit: 'microseconds',
+        frameLimit: 1,
+        eventLimit: 1,
+        phaseCatalog: { app: ['input'], render: ['submit'] },
+        records: [],
+        completeness: {
+          status: 'partial',
+          retainedEventCount: 0,
+          droppedEventCount: 0,
+          incompleteReason: 'stopped-before-frame',
+        },
+      }),
+    );
+
+    expect(complete.status).toBe(0);
+    expect(parseObject(complete.stdout).completeness).toMatchObject({ status: 'complete' });
+    expect(partial.status).toBe(0);
+    expect(parseObject(partial.stdout).completeness).toMatchObject({
+      status: 'partial',
+      incompleteReason: 'stopped-during-frame',
+    });
+    expect(overflow.status).toBe(0);
+    expect(parseObject(overflow.stdout).completeness).toMatchObject({
+      status: 'overflow',
+      droppedEventCount: 7,
+    });
+    expect(empty.status).toBe(0);
+    expect(parseObject(empty.stdout)).toMatchObject({
+      captureId: 'capture-0044',
+      frameCount: 0,
+      frameRange: null,
+      completeness: { status: 'partial' },
+    });
+  });
+
+  it('keeps incompatible artifacts on stderr and repeats deterministically', () => {
+    const input = readFixture('valid-capture.json');
+    const first = runCli(['summary'], input);
+    const second = runCli(['summary'], input);
+    const invalid = runSummaryForFixture('invalid-version.json');
+
+    expect(first.status).toBe(0);
+    expect(second.status).toBe(0);
+    expect(first.stdout).toBe(second.stdout);
+    expect(first.stderr).toBe('');
+    expect(invalid.status).not.toBe(0);
+    expect(invalid.stdout).toBe('');
+    expect(parseObject(invalid.stderr)).toEqual({
+      error: {
+        code: 'profile-artifact-incompatible',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: expect.any(Object),
+      },
+    });
+  });
+
+  it('runs the package consumer smoke through the public CLI entry', () => {
+    const result = spawnSync(process.execPath, [smokePath], {
+      cwd: packageRoot,
+      encoding: 'utf8',
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(parseObject(result.stdout)).toMatchObject({
+      query: 'summary',
+      captureId: 'capture-0010',
+      completeness: { status: 'overflow' },
+    });
+  });
+});

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

@@ -0,0 +1,115 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { runProfilerCli } from '../cli.js';
+
+type CliResponse = Record<string, unknown>;
+
+function readFixture(name: string): string {
+  return readFileSync(new URL(`./fixtures/profile-capture/${name}`, import.meta.url), 'utf8');
+}
+
+function readCliFixture(name: string): string {
+  return readFileSync(new URL(`./fixtures/cli/${name}`, import.meta.url), 'utf8');
+}
+
+function parseOutput(output: string): CliResponse {
+  return JSON.parse(output) as CliResponse;
+}
+
+function expectJsonObject(output: string): CliResponse {
+  const parsed = parseOutput(output);
+  expect(parsed).toEqual(expect.any(Object));
+  return parsed;
+}
+
+describe('profiler CLI structured output contract', () => {
+  it('prints one machine-readable summary object by default', () => {
+    const result = runProfilerCli([], readFixture('valid-complete.json'));
+    const output = expectJsonObject(result.stdout);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(output).toMatchObject({
+      query: 'summary',
+      schemaVersion: '1.0',
+      captureId: 'capture-0001',
+      frameRange: { first: 1, last: 2 },
+      completeness: { status: 'complete' },
+    });
+    expect(output.phases).toEqual(expect.any(Array));
+  });
+
+  it('returns a frame projection selected by frameId', () => {
+    const result = runProfilerCli(['frame', '--frame-id', '2'], readFixture('valid-overflow.json'));
+    const output = expectJsonObject(result.stdout);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(output).toMatchObject({
+      query: 'frame',
+      captureId: 'capture-0002',
+      frameId: 2,
+      completeness: {
+        status: 'overflow',
+        droppedEventCount: 7,
+        firstAffectedFrameId: 2,
+        lastAffectedFrameId: 4,
+      },
+      frame: null,
+    });
+  });
+
+  it('returns a phase projection selected by source and phase', () => {
+    const result = runProfilerCli(
+      ['phase', '--source', 'render', '--phase', 'submit'],
+      readFixture('valid-complete.json'),
+    );
+    const output = expectJsonObject(result.stdout);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(output).toMatchObject({
+      query: 'phase',
+      captureId: 'capture-0001',
+      source: 'render',
+      phase: 'submit',
+      phaseSummary: {
+        source: 'render',
+        phase: 'submit',
+        skipCount: 1,
+      },
+    });
+  });
+
+  it('accepts file input and preserves an empty capture status', () => {
+    const result = runProfilerCli(
+      [
+        'summary',
+        '--file',
+        new URL('./fixtures/profile-capture/valid-complete.json', import.meta.url).pathname,
+      ],
+      '',
+    );
+    const output = expectJsonObject(result.stdout);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(output.completeness).toMatchObject({ status: 'complete' });
+  });
+
+  it('writes one structured error object for an incompatible artifact', () => {
+    const result = runProfilerCli(['summary'], readCliFixture('invalid-version.json'));
+    const error = expectJsonObject(result.stderr);
+
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stdout).toBe('');
+    expect(error).toMatchObject({
+      error: {
+        code: 'profile-artifact-incompatible',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: expect.any(Object),
+      },
+    });
+  });
+});