<?php

declare(strict_types=1);

namespace Drupal\flowdrop_workflow_executor\DTO;

/**
 * Optional per-call overrides for {@see \Drupal\flowdrop_workflow_executor\Service\WorkflowLauncherInterface::launch()}.
 *
 * Public API — part of the launcher's BC surface. Adding fields is fine;
 * removing or repurposing is a BC break.
 *
 * Deliberately small. Two fields today, both extensible and safe to set:
 *
 * - sessionId — bind the run to an existing FlowDrop session (chat-room
 *               launches). Leave null for headless / triggered launches.
 *               The launcher does not interpret sessions itself; it just
 *               records the link on the pipeline so reads can correlate.
 *
 * - wait      — execute the run inline before launch() returns, so the
 *               LaunchResult carries the FINAL pipeline status instead of
 *               PENDING. For drush, cron, queue workers, and kernel tests —
 *               NOT web requests: launch() blocks for the whole run, which
 *               for a stategraph workflow can be up to its `timeout`
 *               budget (300s by default), far past typical FPM limits.
 *               PHP callers only; how an HTTP/websocket caller
 *               waits is a transport-layer concern, deliberately not
 *               FlowDrop's. Ignored (with a logged notice) for workflows
 *               that declare the asynchronous orchestrator — the queue is
 *               the author's declared durability choice and the launcher
 *               never overrides orchestrators. Execution failures do NOT
 *               throw; they land on the pipeline status (`failed`), same
 *               as the deferred path. Outputs are still read via the
 *               pipeline read API — the execute-vs-view permission split
 *               holds regardless of wait.
 *
 * Reserved for future addition (not yet shipped; do not rely on):
 *   - idempotencyKey — needs an indexed lookup design before it can be
 *     honored. Will be added when that's settled.
 *
 * Note: there is intentionally NO orchestrator or dispatch override. The
 * workflow author's declared execution mode is authoritative; allowing
 * callers to substitute it would expose internal implementation as part
 * of the public BC surface, and would defeat the workflow author's intent.
 * If a future need arises (admin tooling, test harnesses), add a
 * permission-gated field rather than opening the public DTO.
 */
final class LaunchOptions {

  public function __construct(
    public readonly ?string $sessionId = NULL,
    public readonly bool $wait = FALSE,
  ) {}

}
