@nsshunt/stsrunnerframework 1.0.200 → 2.0.2

package/types/runnerInstance.d.ts

@@ -0,0 +1,245 @@
+ 
+/**
+ * RunnerInstance
+ * --------------
+ * Concrete runtime implementation of {@link IRunnerEx}.
+ *
+ * A RunnerInstance represents a single executable runner hosted inside a worker.
+ *
+ * Responsibilities:
+ * - Store runner runtime state and metadata
+ * - Dispatch runner commands to the owning worker via the message broker
+ * - Maintain runner telemetry/instrumentation state
+ * - Register runner-level event subscriptions against the owning worker
+ * - Expose full and reduced serialisable runner models
+ *
+ * Design notes:
+ * - A RunnerInstance belongs to exactly one {@link IWorkerEx}.
+ * - Command execution is brokered through {@link STSMessageBroker}; the runner does
+ *   not communicate with the worker directly.
+ * - Event subscriptions are stored on the owning worker, keyed by runner id.
+ */
+import { IAsyncRunnerContext, IExecuteRunnerActionResult, IRunner, IRunnerCore, IRunnerEx, IRunnerOptions, IRunnerState, IRunnerTelemetry, IWorkerEx, IRunnerHistoryRecord } from './commonTypes';
+import { PublishInstrumentController } from '@nsshunt/stsinstrumentmanagerclient';
+import { STSMessageBroker } from './messageBroker';
+/**
+ * Constructor options required to create a {@link RunnerInstance}.
+ *
+ * Notes:
+ * - `workerEx` is the owning live worker instance that hosts this runner.
+ * - `workerManagerId` identifies the top-level owning worker manager.
+ * - `runnerId` is generated elsewhere and supplied to this instance.
+ * - `asyncRunnerContext` contains the logical identity and hierarchy of this runner.
+ * - `runnerOptions` contains runtime configuration for the runner.
+ * - `messageBroker` is used to dispatch commands and correlate responses.
+ * - `publishInstrumentController` is optional and is used when telemetry publishing
+ *   to an external instrumentation system is enabled.
+ */
+export interface IRunnerInstanceOptions {
+    /** Owning live worker instance. */
+    workerEx: IWorkerEx;
+    /** Id of the top-level owning worker manager. */
+    workerManagerId: string;
+    /** Unique id for this runner instance. */
+    runnerId: string;
+    /** Hierarchical runtime context used to identify this runner. */
+    asyncRunnerContext: IAsyncRunnerContext;
+    /** Runner-specific runtime configuration. */
+    runnerOptions: IRunnerOptions;
+    /** Broker used for runner command dispatch and callback correlation. */
+    messageBroker: STSMessageBroker;
+    /** Optional external instrumentation publisher for this runner. */
+    publishInstrumentController?: PublishInstrumentController;
+}
+/**
+ * Concrete live runner runtime instance.
+ *
+ * This class owns:
+ * - the current runtime state of the runner
+ * - its current iteration counter
+ * - its telemetry/instrumentation data
+ * - its configuration/options
+ * - its archived flag and runner history
+ *
+ * This class delegates command execution to the owning worker via
+ * the injected message broker.
+ */
+export declare class RunnerInstance implements IRunnerEx {
+    #private;
+    /** Unique id for this runner instance. */
+    id: string;
+    /** Id of the owning worker instance. */
+    workerId: string;
+    /** Id of the owning worker manager instance. */
+    workerManagerId: string;
+    /**
+     * Current lifecycle state of the runner.
+     *
+     * Defaults to `IRunnerState.created` when the runner instance is first created.
+     */
+    state: IRunnerState;
+    /**
+     * Current iteration number for the runner.
+     *
+     * The meaning of this depends on runner behaviour; typically it tracks
+     * how many execute cycles/iterations have been completed.
+     */
+    iteration: number;
+    /**
+     * Optional instrumentation publisher used for telemetry integration.
+     *
+     * This is only populated when external instrumentation publishing is enabled.
+     */
+    publishInstrumentController?: PublishInstrumentController;
+    /**
+     * Hierarchical runtime identity/context for the runner.
+     *
+     * Typically includes host, agent, worker, and runner identifiers.
+     */
+    asyncRunnerContext: IAsyncRunnerContext;
+    /** Runtime configuration/options for this runner. */
+    options: IRunnerOptions;
+    /**
+     * Historical runner snapshots/events for this runner.
+     *
+     * This is intentionally initialised as an empty array and populated elsewhere
+     * by lifecycle/state management components.
+     */
+    runnerHistory: IRunnerHistoryRecord[];
+    /**
+     * Live telemetry/instrumentation values for this runner.
+     *
+     * These values are updated during runtime as telemetry arrives from the worker.
+     */
+    instrumentData: IRunnerTelemetry;
+    /**
+     * Indicates whether this runner has been archived/retired from active in-memory use.
+     *
+     * This flag is typically managed externally by archive/lifecycle management logic.
+     */
+    archived: boolean;
+    /**
+     * Construct a new live runner runtime instance.
+     *
+     * Behaviour:
+     * - Copies supplied identity and configuration values
+     * - Derives `workerId` from the supplied owning worker
+     * - Stores broker and worker references for later command dispatch
+     * - Initialises telemetry counters/metrics to zeroed defaults
+     *
+     * @param options Construction options and collaborators.
+     */
+    constructor(options: IRunnerInstanceOptions);
+    /**
+     * Send a `StartRunner` command for this runner via the message broker.
+     *
+     * @returns Action result returned by the worker.
+     */
+    Start(): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `StopRunner` command for this runner via the message broker.
+     *
+     * @returns Action result returned by the worker.
+     */
+    Stop(): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `PauseRunner` command for this runner via the message broker.
+     *
+     * @returns Action result returned by the worker.
+     */
+    Pause(): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `ResumeRunner` command for this runner via the message broker.
+     *
+     * @returns Action result returned by the worker.
+     */
+    Resume(): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `ResetRunner` command for this runner via the message broker.
+     *
+     * @returns Action result returned by the worker.
+     */
+    Reset(): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send an `ExecuteRunner` command for this runner via the message broker.
+     *
+     * @returns Action result returned by the worker.
+     */
+    Execute(): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `TerminateRunner` command for this runner via the message broker.
+     *
+     * @returns Action result returned by the worker.
+     */
+    Terminate(): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send an `UpdateRunner` command for this runner via the message broker.
+     *
+     * Behaviour:
+     * - Sends the supplied partial options to the underlying worker
+     * - The worker is responsible for applying/merging the update as appropriate
+     *
+     * @param runnerOptions Partial runner option updates to apply.
+     * @returns Action result returned by the worker.
+     */
+    Update(runnerOptions: Partial<IRunnerOptions>): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Register a runner-level event subscription.
+     *
+     * Behaviour:
+     * - Stores the subscription on the owning worker in `runnersEvents`
+     * - Creates the per-runner event list lazily if it does not yet exist
+     * - Returns this runner instance to support fluent chaining
+     *
+     * Notes:
+     * - Runner event subscriptions are hosted on the worker because the worker is
+     *   the aggregate owner of all live runner instances.
+     *
+     * @param eventName Event name to subscribe to.
+     * @param cb Callback invoked when the event is emitted for this runner.
+     * @returns This runner instance for fluent chaining.
+     */
+    on(eventName: string, cb: (args?: any) => void): IRunnerEx;
+    /**
+     * Convert this live runner runtime instance into a full serialisable runner model.
+     *
+     * Behaviour:
+     * - Copies runner metadata and state
+     * - Creates shallow copies of nested objects used by the DTO
+     * - Copies telemetry messages into a new array to avoid external mutation
+     * - Includes full `runnerHistory`
+     *
+     * @returns Full serialisable runner model.
+     */
+    toJSON(): IRunner;
+    /**
+     * Convert this runner into a serialisable runner model with optional history exclusion.
+     *
+     * Behaviour:
+     * - When `includeHistory` is `true`, returns the full runner DTO from {@link toJSON}
+     * - When `includeHistory` is `false`, removes `runnerHistory` from the returned model
+     *
+     * This is useful when sending a lighter-weight runner payload over message channels.
+     *
+     * @param includeHistory Whether to include `runnerHistory` in the returned DTO.
+     * @returns Full or reduced serialisable runner model.
+     */
+    toRunner(includeHistory?: boolean): IRunner;
+    /**
+     * Convert this runner into a reduced/core representation.
+     *
+     * Behaviour:
+     * - Includes only the minimal runtime state required for lightweight summaries
+     * - Includes `runnerPlan` when present in the runner options
+     *
+     * Intended use cases:
+     * - lightweight dashboards
+     * - summary views
+     * - state-only synchronisation payloads
+     *
+     * @returns Reduced/core runner DTO.
+     * @throws Re-throws any error after logging.
+     */
+    toRunnerCore(): IRunnerCore;
+}
+//# sourceMappingURL=runnerInstance.d.ts.map

package/types/runnerInstance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerInstance.d.ts","sourceRoot":"","sources":["../src/runnerInstance.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEH,mBAAmB,EACnB,0BAA0B,EAE1B,OAAO,EACP,WAAW,EAEX,SAAS,EACT,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,oBAAoB,EACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACnC,mCAAmC;IACnC,QAAQ,EAAE,SAAS,CAAC;IAEpB,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IAExB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,iEAAiE;IACjE,kBAAkB,EAAE,mBAAmB,CAAC;IAExC,6CAA6C;IAC7C,aAAa,EAAE,cAAc,CAAC;IAE9B,wEAAwE;IACxE,aAAa,EAAE,gBAAgB,CAAC;IAEhC,mEAAmE;IACnE,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;CAC7D;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,YAAW,SAAS;;IAC5C,0CAA0C;IACnC,EAAE,EAAE,MAAM,CAAC;IAElB,wCAAwC;IACjC,QAAQ,EAAE,MAAM,CAAC;IAExB,gDAAgD;IACzC,eAAe,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACI,KAAK,EAAE,YAAY,CAAwB;IAElD;;;;;OAKG;IACI,SAAS,SAAK;IAErB;;;;OAIG;IACI,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;IAEjE;;;;OAIG;IACI,kBAAkB,EAAE,mBAAmB,CAAC;IAE/C,qDAAqD;IAC9C,OAAO,EAAE,cAAc,CAAC;IAE/B;;;;;OAKG;IACI,aAAa,EAAE,oBAAoB,EAAE,CAAO;IAEnD;;;;OAIG;IACI,cAAc,EAAE,gBAAgB,CAAC;IAExC;;;;OAIG;IACI,QAAQ,UAAS;IAQxB;;;;;;;;;;OAUG;gBACS,OAAO,EAAE,sBAAsB;IAmC3C;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI5C;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI3C;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI5C;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI7C;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI5C;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI9C;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAIhD;;;;;;;;;OASG;IACH,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAInF;;;;;;;;;;;;;;;OAeG;IACH,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,GAAG,SAAS;IAa1D;;;;;;;;;;OAUG;IACH,MAAM,IAAI,OAAO;IAiBjB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,cAAc,UAAO,GAAG,OAAO;IAUxC;;;;;;;;;;;;;;OAcG;IACH,YAAY,IAAI,WAAW;CA8C9B"}

package/types/runnerLifecycleManager.d.ts

@@ -0,0 +1,210 @@
+ 
+/**
+ * RunnerLifecycleManager
+ * ----------------------
+ * Runtime lifecycle/event processor responsible for handling unsolicited
+ * runner-related messages received from workers.
+ *
+ * Responsibilities:
+ * - process unsolicited telemetry messages pushed from workers
+ * - process unsolicited runner state change messages pushed from workers
+ * - update live in-memory runner state in the {@link WorkerRegistry}
+ * - trigger telemetry publishing via {@link TelemetryProcessor}
+ * - emit runner-level events to registered listeners
+ * - provide a message-handler factory suitable for wiring into the message broker
+ *
+ * High-level role in the architecture:
+ * - Workers push unsolicited messages such as telemetry and state changes
+ * - The {@link STSMessageBroker} routes those unsolicited messages to a callback
+ * - This class provides that callback and applies the updates to live runner instances
+ *
+ * Important distinction:
+ * - Solicited request/response traffic is handled by the message broker
+ * - Unsolicited push/event traffic is handled here
+ *
+ * Typical unsolicited messages handled here:
+ * - `InstrumentTelemetry`
+ * - `RunnerStateChange`
+ */
+import { IWorkerEx, IRunner, IRunnerEx } from './commonTypes';
+import { WorkerRegistry } from './workerRegistry';
+import { ISTSLogger } from '@nsshunt/stsutils';
+/**
+ * Constructor options for {@link RunnerLifecycleManager}.
+ */
+export interface IRunnerLifecycleManagerOptions {
+    /**
+     * Logger used for diagnostics and error reporting.
+     */
+    logger: ISTSLogger;
+    /**
+     * Shared live worker/runner registry used to resolve and update
+     * the current runtime runner instances.
+     */
+    workerRegistry: WorkerRegistry;
+}
+/**
+ * Manages live runner lifecycle updates for unsolicited worker messages.
+ *
+ * This class updates the in-memory runtime graph and emits runner events
+ * in response to messages pushed by workers.
+ */
+export declare class RunnerLifecycleManager {
+    /**
+     * Immutable runtime configuration for this lifecycle manager.
+     */
+    private readonly options;
+    /**
+     * Processor used to forward/update external telemetry instrumentation.
+     *
+     * This is created eagerly in the constructor and used only when a runner
+     * has a publish instrument controller attached.
+     */
+    private readonly telemetryProcessor;
+    /**
+     * Construct a new runner lifecycle manager.
+     *
+     * @param options Logger and worker registry dependencies.
+     */
+    constructor(options: IRunnerLifecycleManagerOptions);
+    /**
+     * Process an unsolicited telemetry message for a runner.
+     *
+     * Behaviour:
+     * - resolves the live runner instance from the registry
+     * - updates the live runner state/telemetry using {@link SyncRunnerData}
+     * - if the runner has a publish instrument controller, pushes the telemetry
+     *   through the {@link TelemetryProcessor}
+     * - emits a `Telemetry` runner event
+     *
+     * Notes:
+     * - This method only handles unsolicited push telemetry from workers
+     * - The incoming payload is expected to contain a serialised `runner`
+     *   snapshot with updated instrumentation values
+     *
+     * @param workerEx Worker that produced the telemetry message.
+     * @param payloadContents Telemetry payload containing the updated runner snapshot.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    private _ProcessTelemetry;
+    /**
+     * Emit a runner-level event for a specific runner.
+     *
+     * Behaviour:
+     * - looks up all registered event handlers for the specified runner id
+     * - filters to handlers whose `eventName` matches the supplied event name
+     * - resolves the live runner instance from the registry
+     * - invokes each matching callback with the live runner instance
+     *
+     * Notes:
+     * - Event subscriptions are stored on the worker in `workerEx.runnersEvents`
+     * - The live runner instance is resolved from the registry at emit time so
+     *   callbacks receive the current runtime object
+     *
+     * @param eventName Name of the runner event to emit.
+     * @param workerEx Owning worker of the runner.
+     * @param runnerId Id of the runner whose event should be emitted.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    private _EmitRunnerEvent;
+    /**
+     * Process an unsolicited runner state change message.
+     *
+     * Behaviour:
+     * - resolves the live runner instance from the registry
+     * - records the previous state for logging/debugging
+     * - updates the runner's current state
+     * - appends a runner-history entry containing a snapshot of the new state
+     * - ensures nested `runnerHistory` is cleared from the history snapshot itself
+     *   to avoid recursive history growth
+     * - updates other live runner fields via {@link SyncRunnerData}
+     * - emits a `StateChange` runner event
+     *
+     * History entry structure:
+     * - `eventDate`: timestamp when the state change was processed
+     * - `runner`: shallow copy of the inbound runner snapshot
+     *
+     * Notes:
+     * - This is intended for unsolicited push state updates from the worker
+     * - The runner history list is lazily initialised if missing
+     *
+     * @param workerEx Worker that produced the state change.
+     * @param payloadContents Payload containing the updated runner snapshot.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    private _RunnerStateChange;
+    /**
+     * Synchronise live mutable runner fields from a serialised runner snapshot.
+     *
+     * Behaviour:
+     * - updates iteration
+     * - updates state
+     * - replaces the current instrumentation payload
+     *
+     * Intended use:
+     * - telemetry processing
+     * - worker state synchronisation
+     * - state change handling
+     *
+     * Notes:
+     * - This method mutates the live `runnerEx` instance directly
+     * - It intentionally updates only the current mutable runtime fields and not
+     *   the full runner identity/options model
+     *
+     * @param runnerEx Live runner instance to update.
+     * @param runner Serialised runner snapshot containing updated values.
+     */
+    SyncRunnerData: (runnerEx: IRunnerEx, runner: IRunner) => void;
+    /**
+     * Build the list of unsolicited command handlers supported by this lifecycle manager.
+     *
+     * Current unsolicited commands handled:
+     * - `InstrumentTelemetry`
+     * - `RunnerStateChange`
+     *
+     * Each mapping contains:
+     * - `command`: the incoming message command
+     * - `cb`: the handler to invoke for that command
+     *
+     * Notes:
+     * - This method currently rebuilds the list on each call
+     * - Since the mapping is small and static, this is acceptable, though it could
+     *   be cached later if desired
+     *
+     * @returns Array of unsolicited command -> handler mappings.
+     */
+    private _GetUnsolicitedCommandProcessMap;
+    /**
+     * Create a message handler function suitable for wiring into a worker's
+     * unsolicited-message listener.
+     *
+     * Behaviour of the returned handler:
+     * - interprets the inbound raw data as an {@link IIWMessagePayload}
+     * - finds a matching unsolicited command handler from the internal map
+     * - if a handler is found, invokes it with:
+     *   - the specific worker instance for which this handler was created
+     *   - the inbound message payload cast as `ITestRunnerTelemetryPayload`
+     *
+     * Typical usage:
+     * - one handler is created per worker
+     * - that handler is passed into the message broker's port-listener setup
+     * - the handler processes only unsolicited push/event traffic
+     *
+     * Notes:
+     * - This method intentionally closes over `stsWorkerEx`, so the returned
+     *   handler is permanently associated with that worker instance
+     * - Solicited request/response messages should already have been handled
+     *   by the message broker before reaching this handler
+     *
+     * Future design note:
+     * - Runner state changes may eventually be fully embedded in solicited responses,
+     *   which could make separate `RunnerStateChange` push events redundant and reduce
+     *   race conditions between awaited commands and subsequent push updates
+     *
+     * @param stsWorkerEx Worker instance whose unsolicited messages should be processed.
+     * @returns A function that processes unsolicited messages for the supplied worker.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    ProcessMessageHandlerFactory: (stsWorkerEx: IWorkerEx) => (data: any) => void;
+}
+//# sourceMappingURL=runnerLifecycleManager.d.ts.map

package/types/runnerLifecycleManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerLifecycleManager.d.ts","sourceRoot":"","sources":["../src/runnerLifecycleManager.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAGH,SAAS,EACT,OAAO,EACP,SAAS,EAGZ,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC3C;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;CAClC;AAED;;;;;GAKG;AACH,qBAAa,sBAAsB;IAC/B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEzD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAmC;IAEtE;;;;OAIG;gBACS,OAAO,EAAE,8BAA8B;IAKnD;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,iBAAiB,CAqBvB;IAEF;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,gBAAgB,CAkBtB;IAEF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,kBAAkB,CAwCxB;IAEF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,GAAI,UAAU,SAAS,EAAE,QAAQ,OAAO,UAQpD;IAEF;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,gCAAgC,CAKtC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,4BAA4B,GAAI,aAAa,SAAS,MAC1C,MAAM,GAAG,UAgBnB;CACL"}

package/types/telemetryProcessor.d.ts

@@ -1,6 +1,73 @@
+/**
+ * TelemetryProcessor
+ * ------------------
+ * Responsible for translating raw runner telemetry into updates for the
+ * observability instrumentation system.
+ *
+ * This class acts as the bridge between:
+ *
+ *  - the internal runner telemetry model (`IRunnerTelemetry`)
+ *  - the external observability instrumentation system
+ *    (`PublishInstrumentController` from `@nsshunt/stsinstrumentmanagerclient`)
+ *
+ * The processor interprets telemetry values and updates the appropriate
+ * gauges, counters, and histograms defined in the observability model
+ * (`@nsshunt/stsobservability`).
+ *
+ * High-level responsibilities:
+ *
+ * 1. Convert runner telemetry fields into instrumentation updates
+ * 2. Push those updates to the PublishInstrumentController
+ * 3. Forward any telemetry log messages
+ * 4. Track whether any meaningful update occurred
+ *
+ * The processor is intentionally stateless. It simply transforms and forwards
+ * telemetry values.
+ */
 import { PublishInstrumentController } from '@nsshunt/stsinstrumentmanagerclient';
 import { IRunnerTelemetry } from "./commonTypes";
+/**
+ * Processes telemetry emitted by a runner and forwards it to the
+ * instrumentation subsystem.
+ */
 export declare class TelemetryProcessor {
+    /**
+     * Process telemetry data for a runner and publish it through the
+     * provided instrumentation controller.
+     *
+     * Behaviour:
+     *
+     * - Each telemetry field is mapped to one or more observability gauges.
+     * - Only fields with values are processed (except active request count,
+     *   which is always updated).
+     * - Some telemetry values update gauges using:
+     *
+     *      val → set absolute value
+     *      Inc → increment existing metric
+     *
+     * - Histogram gauges are updated alongside standard gauges for
+     *   latency and duration metrics.
+     *
+     * Logging behaviour:
+     *
+     * - Any telemetry messages present in `telemetry.message`
+     *   are forwarded to the publish instrument controller via `LogEx`.
+     *
+     * Return value:
+     *
+     * - `true` if any telemetry fields were processed and published
+     * - `false` if no update occurred
+     *
+     * @param publishInstrumentController
+     * Controller responsible for publishing metrics/logs to the
+     * observability system.
+     *
+     * @param telemetry
+     * Raw telemetry snapshot generated by a runner execution cycle.
+     *
+     * @returns
+     * Boolean indicating whether telemetry updates were applied.
+     */
     ProcessTelemetry: (publishInstrumentController: PublishInstrumentController, telemetry: IRunnerTelemetry) => boolean;
 }
 //# sourceMappingURL=telemetryProcessor.d.ts.map

package/types/telemetryProcessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetryProcessor.d.ts","sourceRoot":"","sources":["../src/telemetryProcessor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,qBAAa,kBAAkB;IAC3B,gBAAgB,GAAI,6BAA6B,2BAA2B,EAAE,WAAW,gBAAgB,KAAG,OAAO,CAuHlH;CACJ"}
+{"version":3,"file":"telemetryProcessor.d.ts","sourceRoot":"","sources":["../src/telemetryProcessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAmFjD;;;GAGG;AACH,qBAAa,kBAAkB;IAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,gBAAgB,GACZ,6BAA6B,2BAA2B,EACxD,WAAW,gBAAgB,KAC5B,OAAO,CAkNT;CACJ"}

package/types/testing/mockedWorkerTestRunner01.d.ts

@@ -1,9 +1,136 @@
-import { IRunnerInstance, ITestRunnerTelemetryPayload, WorkerInstance } from './../index';
+ 
+/**
+ * WorkerTestCases
+ * ===============
+ *
+ * Concrete test worker implementation used to exercise and validate the
+ * runner framework.
+ *
+ * Purpose
+ * -------
+ * This class acts as a specialised worker-runtime host for framework tests.
+ * It extends {@link AbstractRunnerExecutionWorker} and provides concrete
+ * runner creation logic for known test-case runners.
+ *
+ * In other words, this class is the test implementation of the abstract
+ * worker-side execution host.
+ *
+ * It is responsible for:
+ * - receiving the transferred message port when used in mocked/manual setups
+ * - wiring incoming messages from that port into the standard worker message pipeline
+ * - creating the appropriate concrete test runner based on `runner.options.testType`
+ *
+ * Typical usage
+ * -------------
+ * This class is useful when validating that the runner framework correctly handles:
+ *
+ * - worker bootstrap
+ * - message routing
+ * - runner creation
+ * - start/stop/pause/resume/reset/update flows
+ * - telemetry flow
+ * - state transitions
+ * - multiple concrete runner implementations behind the same worker host
+ *
+ * Supported test runners
+ * ----------------------
+ * Currently this worker can create:
+ *
+ * - {@link TestCase01}
+ * - {@link TestCase02}
+ *
+ * The specific runner created is determined by:
+ *
+ * `runner.options.testType`
+ *
+ * Architecture note
+ * -----------------
+ * `WorkerTestCases` lives on the **worker-runtime side** of the framework.
+ * It is not the manager/controller. Instead, it is the concrete worker-host
+ * that runs inside the actual worker or mocked worker environment.
+ */
+import { IRunnerInstance, ITestRunnerTelemetryPayload } from './../index';
+import { AbstractRunnerExecutionWorker } from './../abstractRunnerExecutionWorker';
 import { JSONObject } from '@nsshunt/stsutils';
-export declare class WorkerTestCases extends WorkerInstance {
+/**
+ * Concrete test worker implementation for the runner framework.
+ *
+ * This class extends {@link AbstractRunnerExecutionWorker} and supplies
+ * concrete runner creation logic for framework test cases.
+ */
+export declare class WorkerTestCases extends AbstractRunnerExecutionWorker {
     #private;
+    /**
+     * Construct the test worker.
+     *
+     * Behaviour:
+     * - delegates to {@link AbstractRunnerExecutionWorker} constructor
+     * - starts the inherited background cleanup/archive loop
+     * - prepares the worker to accept port/message bootstrap via `SetPort(...)`
+     */
     constructor();
+    /**
+     * Manually set and wire the communication port for this worker.
+     *
+     * Purpose
+     * -------
+     * This method is particularly useful in mocked or direct in-process test
+     * environments where the framework cannot rely on normal native worker
+     * bootstrap semantics.
+     *
+     * Behaviour
+     * ---------
+     * - extracts the transferred port from the supplied message payload
+     * - stores that port locally
+     * - attaches a message listener to the port
+     * - forwards inbound messages to the inherited `ProcessMessage(...)` pipeline
+     * - finally passes the original bootstrap message into `ProcessMessage(...)`
+     *   so the base class can complete normal worker bootstrap handling
+     *
+     * Environment handling
+     * --------------------
+     * Node.js:
+     * - incoming data is passed directly to `ProcessMessage(data)`
+     *
+     * Browser:
+     * - incoming data is expected inside `data.data`
+     * - forwards `ProcessMessage(data.data)`
+     *
+     * Notes
+     * -----
+     * The supplied `message` is expected to contain:
+     *
+     * - `payload.port`
+     *
+     * and to otherwise resemble the framework's normal worker bootstrap message.
+     *
+     * @param message Bootstrap-style message containing the manager communication port.
+     */
     SetPort: (message: JSONObject) => void;
+    /**
+     * Create a concrete test runner instance for the supplied runner payload.
+     *
+     * Behaviour
+     * ---------
+     * - inspects `runner.options.testType`
+     * - creates the matching concrete test runner implementation
+     * - returns that runner to the base worker host
+     *
+     * Supported values
+     * ----------------
+     * - `TestCase01` -> creates {@link TestCase01}
+     * - `TestCase02` -> creates {@link TestCase02}
+     *
+     * If the `testType` is not recognised, `null` is returned, indicating
+     * that no executable runner could be created.
+     *
+     * This method is the key test-specific extension point that makes this
+     * class a usable concrete implementation of
+     * {@link AbstractRunnerExecutionWorker}.
+     *
+     * @param testRunnerTelemetryPayload Runner creation payload from the framework.
+     * @returns Concrete test runner instance, or `null` if the requested test type is unsupported.
+     */
     CreateAsyncRunner: (testRunnerTelemetryPayload: ITestRunnerTelemetryPayload) => Promise<IRunnerInstance | null>;
 }
 //# sourceMappingURL=mockedWorkerTestRunner01.d.ts.map

package/types/testing/mockedWorkerTestRunner01.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mockedWorkerTestRunner01.d.ts","sourceRoot":"","sources":["../../src/testing/mockedWorkerTestRunner01.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,2BAA2B,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAOzF,OAAO,EAAc,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE3D,qBAAa,eAAgB,SAAQ,cAAc;;;IAO/C,OAAO,GAAI,SAAS,UAAU,UAa7B;IAEQ,iBAAiB,GAAU,4BAA4B,2BAA2B,KAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAS5H;CACJ"}
+{"version":3,"file":"mockedWorkerTestRunner01.d.ts","sourceRoot":"","sources":["../../src/testing/mockedWorkerTestRunner01.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAQnF,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,6BAA6B;;IAW9D;;;;;;;OAOG;;IAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,OAAO,GAAI,SAAS,UAAU,UAoB5B;IAEF;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACM,iBAAiB,GACtB,4BAA4B,2BAA2B,KACxD,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAYhC;CACL"}