// SPDX-License-Identifier: GPL-2.0-or-later
// Copyright (C) 2026 Bryan Joshua Pedini

/**
 * Test-infrastructure errors.
 *
 * A HarnessError means "the harness could not obtain a trustworthy observation"
 * (timeout, unexpected signal, hung process, spawn failure, leaked resource,
 * missing prerequisite, unparseable protocol data). It is never a valid outcome
 * for an expected-failure assertion: helpers throw it instead of returning a
 * result, so a negative test can never pass because something crashed or hung.
 */
export type HarnessErrorKind =
  | 'timeout' // a process / request / wait exceeded its deadline
  | 'signal' // a process was terminated by a signal nobody asked for
  | 'spawn' // a process could not be started
  | 'hang' // a process did not exit after being asked to
  | 'leak' // a resource (process, container, directory) outlived its owner
  | 'prerequisite' // the environment is missing something the suite needs
  | 'protocol' // a peer produced data the harness cannot parse
  | 'transport' // an HTTP client failed below HTTP (refused, reset) where a response was required
  | 'infrastructure'; // anything else that is the harness's fault, not the app's

export class HarnessError extends Error {
  readonly kind: HarnessErrorKind;
  readonly details?: unknown;

  constructor(kind: HarnessErrorKind, message: string, details?: unknown) {
    super(`[harness:${kind}] ${message}`);
    this.name = 'HarnessError';
    this.kind = kind;
    this.details = details;
  }
}

export function isHarnessError(e: unknown): e is HarnessError {
  return e instanceof HarnessError;
}