<?php

declare(strict_types=1);

namespace Drupal\native_observability_execution\Service;

/**
 * Stores execution spans for the current request.
 *
 * This is an in-memory collector meant for per-request aggregation.
 * Persistence/export will be handled by the core storage layer when integrated.
 */
final class ExecutionSpanStack {

  /**
   * The collected execution spans for the current request.
   *
   * @var array<int, array<string, mixed>>
   */
  private array $spans = [];

  /**
   * Adds a new span to the stack.
   *
   * @param array<string, mixed> $span
   *   A normalized span payload (name, start, end, duration, metadata).
   */
  public function add(array $span): void {
    $this->spans[] = $span;
  }

  /**
   * Returns all collected spans.
   *
   * @return array<int, array<string, mixed>>
   *   The collected spans.
   */
  public function all(): array {
    return $this->spans;
  }

  /**
   * Clears the stack.
   */
  public function reset(): void {
    $this->spans = [];
  }

}
