<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Exception;

/**
 * Thrown when a node returns output that cannot be persisted as JSON.
 *
 * Every execution engine (synchronous, asynchronous, StateGraph) persists
 * node output through json_encode — job records and StateGraph checkpoints
 * alike. A value json_encode cannot faithfully encode (a loaded entity, a
 * Url, a Markup object, a closure, a resource) is silently mangled to an
 * empty object at that boundary and cannot be re-read by a downstream node,
 * producing engine-dependent data loss that passes in the in-memory
 * synchronous path and fails only once persisted.
 *
 * The runtime rejects such output at the single point all engines converge,
 * so the failure names the node that produced it rather than surfacing as
 * empty data several jobs later. It is a processor contract violation — a
 * code bug the node author must fix by reducing entities to references
 * (e.g. {entity_type, id}) before returning them.
 *
 * Thrown inside NodeRuntimeService's processor try block, it surfaces as a
 * non-retryable error Output (this exception does not implement
 * RetryableExceptionInterface): the node follows its normal failure path —
 * error-edge routing where the author declared one, else failing the run.
 *
 * @internal
 *   This class is not part of the public API and may change without notice.
 */
class NonSerializableOutputException extends DataFlowException {

}
