Address reporter contract review feedback

Assistant-model: GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 90cfc9a4-cbde-48e6-a771-86ad7abf948c

Author: TheLarkInn

common/reviews/api/reporter.api.md

@@ -63,7 +63,7 @@ export interface IReporterContext {
 }
 
 // @beta
-export type IReporterEmitEventInput<TPayload> = Omit<IReporterEventEnvelope<TPayload>, 'eventId' | 'sequence' | 'timestamp'>;
+export type IReporterEmitEventInput<TPayload> = Omit<IReporterEventEnvelope<TPayload>, 'eventId' | 'sequence' | 'sourceSequence' | 'timestamp'>;
 
 // @beta
 export interface IReporterEventEnvelope<TPayload = unknown> {
@@ -118,19 +118,19 @@ export interface IReporterHandshakeResult {
 
 // @beta
 export interface IReporterHello {
-    readonly capabilities: string[];
+    readonly capabilities: readonly string[];
     readonly kind: 'hello';
     readonly producerVersion: string;
     readonly protocolVersion: IReporterProtocolVersion;
-    readonly requiredFeatures: string[];
+    readonly requiredFeatures: readonly string[];
 }
 
 // @beta
 export interface IReporterHelloAck {
-    readonly acceptedCapabilities: string[];
+    readonly acceptedCapabilities: readonly string[];
     readonly kind: 'helloAck';
     readonly protocolVersion: IReporterProtocolVersion;
-    readonly rejectedRequiredFeatures: string[];
+    readonly rejectedRequiredFeatures: readonly string[];
 }
 
 // @beta

libraries/reporter/README.md

@@ -6,9 +6,8 @@ This package is released as a public beta. Exported contracts may change before
 
 ## Links
 
-- [CHANGELOG.md](
-  https://github.com/microsoft/rushstack/blob/main/libraries/reporter/CHANGELOG.md) - Find
-  out what's new in the latest version
+- [CHANGELOG.md](https://github.com/microsoft/rushstack/blob/main/libraries/reporter/CHANGELOG.md) - Find out
+  what's new in the latest version
 - [API Reference](https://api.rushstack.io/pages/reporter/)
 
 `@rushstack/reporter` is part of the [Rush Stack](https://rushstack.io/) family of projects.

libraries/reporter/src/manager/ReporterManager.ts

@@ -179,6 +179,7 @@ export class ReporterManager implements IReporterEventSink {
    * `timestamp`, and returns the assigned `eventId`.
    */
   public emit<TPayload>(event: IReporterEmitEventInput<TPayload>): string {
+    this._ensureInitialized();
     const eventId: string = `evt_${this._nextEventId++}`;
     const envelope: IReporterEventEnvelope<TPayload> = {
       ...event,
@@ -200,6 +201,7 @@ export class ReporterManager implements IReporterEventSink {
    * @returns the ingested event's `eventId`
    */
   public ingestForeignEnvelope(envelope: IReporterEventEnvelope<unknown>): string {
+    this._ensureInitialized();
     const rehomed: IReporterEventEnvelope<unknown> = {
       ...envelope,
       sequence: this._nextSequence++,
@@ -273,6 +275,12 @@ export class ReporterManager implements IReporterEventSink {
     }
   }
 
+  private _ensureInitialized(): void {
+    if (!this._initialized) {
+      throw new Error('ReporterManager must be initialized before publishing events.');
+    }
+  }
+
   private _enqueue(entry: IReporterEntry, envelope: IReporterEventEnvelope<unknown>): void {
     const lastIndex: number = entry.queue.length - 1;
     if (

libraries/reporter/src/producers/IReporterEventSink.ts

@@ -7,14 +7,14 @@ import type { IReporterEventEnvelope } from '../events/IReporterEventEnvelope';
  * The fields of an event envelope that a producer supplies when emitting.
  *
  * @remarks
- * The sink assigns `eventId`, the authoritative `sequence`, and the `timestamp`,
- * so producers never provide them.
+ * The sink assigns `eventId`, the authoritative `sequence`, `sourceSequence`,
+ * and the `timestamp`, so producers never provide them.
  *
  * @beta
  */
 export type IReporterEmitEventInput<TPayload> = Omit<
   IReporterEventEnvelope<TPayload>,
-  'eventId' | 'sequence' | 'timestamp'
+  'eventId' | 'sequence' | 'sourceSequence' | 'timestamp'
 >;
 
 /**
@@ -32,7 +32,7 @@ export interface IReporterEventSink {
    * Publishes an event and returns its assigned event id.
    *
    * @param event - the event envelope without the sink-assigned `eventId`,
-   * `sequence`, and `timestamp`
+   * `sequence`, `sourceSequence`, and `timestamp`
    * @returns the `eventId` assigned to the published event
    */
   emit<TPayload>(event: IReporterEmitEventInput<TPayload>): string;

libraries/reporter/src/producers/IScopedReporter.ts

@@ -58,7 +58,7 @@ export interface IScopedReporter {
   emitMessage(options: IScopedMessageOptions): string;
 
   /**
-   * Emits a structured diagnostic and returns its assigned diagnostic id.
+   * Emits a structured diagnostic and returns its assigned event id.
    */
   emitDiagnostic(diagnostic: IRushDiagnostic): string;
 

libraries/reporter/src/protocol/ReporterHandshake.ts

@@ -30,12 +30,12 @@ export interface IReporterHello {
   /**
    * Optional capabilities the producer can use if the consumer supports them.
    */
-  readonly capabilities: string[];
+  readonly capabilities: readonly string[];
 
   /**
    * Correctness-critical features the producer requires the consumer to support.
    */
-  readonly requiredFeatures: string[];
+  readonly requiredFeatures: readonly string[];
 }
 
 /**
@@ -57,12 +57,12 @@ export interface IReporterHelloAck {
   /**
    * The subset of the producer's capabilities the consumer accepted.
    */
-  readonly acceptedCapabilities: string[];
+  readonly acceptedCapabilities: readonly string[];
 
   /**
    * The producer's required features the consumer does not support.
    */
-  readonly rejectedRequiredFeatures: string[];
+  readonly rejectedRequiredFeatures: readonly string[];
 }
 
 /**

libraries/reporter/src/test/Manager.test.ts

@@ -64,6 +64,32 @@ function makeInput(
 }
 
 describe('ReporterManager ordering and assignment', () => {
+  it('rejects in-process events before reporters are initialized', () => {
+    const manager: ReporterManager = new ReporterManager();
+    manager.addReporter(new RecordingReporter('a'));
+
+    expect(() => manager.emit(makeInput('commandStarted'))).toThrow(/must be initialized/);
+  });
+
+  it('rejects foreign envelopes before reporters are initialized', () => {
+    const manager: ReporterManager = new ReporterManager();
+    manager.addReporter(new RecordingReporter('a'));
+    const foreign: IReporterEventEnvelope<unknown> = {
+      protocolVersion: { major: 1, minor: 0 },
+      eventId: 'child_evt',
+      sessionId: 'child',
+      sequence: 42,
+      timestamp: '2026-01-01T00:00:01.000Z',
+      source: { packageName: '@rushstack/heft', packageVersion: '1.2.19' },
+      privacy: 'public',
+      required: false,
+      type: 'externalOutput',
+      payload: {}
+    };
+
+    expect(() => manager.ingestForeignEnvelope(foreign)).toThrow(/must be initialized/);
+  });
+
   it('assigns monotonic sequence, event ids, and timestamps in order', async () => {
     const manager: ReporterManager = new ReporterManager({ now: () => '2026-01-01T00:00:00.000Z' });
     const reporter: RecordingReporter = new RecordingReporter('a');