/**
 * Graph node accepted by ExFlow.
 */
type ExFlowSafeData = {
    /**
     * Reserved internal metadata field injected by ExFlow.
     * User data types must not declare it.
     */
    exFlowPriority?: never;
};
/**
 * Helper alias for consumer models that must remain compatible with ExFlow input constraints.
 */
type SafeTask<T extends object> = T & ExFlowSafeData;
/**
 * Graph node accepted by ExFlow.
 */
interface ExNode<T extends object & ExFlowSafeData> {
    /** Unique node id. */
    id: string;
    /** Task payload. */
    data: T;
    /** Node ids that must complete before this node can execute. */
    dependsOn: string[];
    /** Optional priority used for ordering inside the same execution batch. */
    priority?: number;
    /** Optional resource class used with resource cap constraints. */
    resourceClass?: string;
    /** Optional deadline score used by deadline ordering strategies. */
    deadline?: number;
    /** Optional weight score used by weight ordering strategies. */
    weight?: number;
}
/** Clone policy used when ExFlow creates result items. */
type ExFlowCloneMode = "shallow" | "deep" | "custom";
type ExFlowTieBreaker<T extends object & ExFlowSafeData> = (a: Readonly<ExNode<T>>, b: Readonly<ExNode<T>>) => number;
type DeadlineStrategy = "earliest-first" | "latest-first";
type WeightStrategy = "higher-first" | "lower-first";
type ExFlowSchedulerMode = "level" | "throughput";
type ExFlowTieFallbackPolicy = "insertion" | "id-asc" | "id-desc";
type ExFlowFairnessPolicy = "none" | "aging";
type ExFlowPresetName = "stable-enterprise" | "high-throughput" | "strict-fairness";
/**
 * Runtime options for ExFlow.
 */
interface ExFlowOptions<T extends object & ExFlowSafeData> {
    /**
     * Clone behavior for output items.
     * Defaults to `shallow`.
     */
    cloneMode?: ExFlowCloneMode;
    /**
     * Custom clone function used only when cloneMode is `custom`.
     */
    cloneFn?: (data: T) => T;
    /**
     * If true, nodes with lower priority values are executed first.
     * Defaults to `false` (higher priority first).
     */
    priorityAscending?: boolean;
    /**
     * Optional tie-breaker used when two nodes have the same priority.
     * When provided, ExFlow switches to a compare-based sort implementation.
     */
    tieBreaker?: ExFlowTieBreaker<T>;
    /**
     * Optional maximum number of nodes allowed in a single emitted batch.
     */
    concurrencyCap?: number;
    /**
     * Optional per-resource-class caps for nodes emitted in the same batch.
     */
    resourceCaps?: Record<string, number>;
    /**
     * Optional strategy for ordering by node deadline.
     */
    deadlineStrategy?: DeadlineStrategy;
    /**
     * Optional strategy for ordering by node weight.
     */
    weightStrategy?: WeightStrategy;
    /**
     * Scheduler mode:
     * - `level` keeps strict level-by-level release.
     * - `throughput` can unlock and schedule newly-ready nodes between constrained sub-batches.
     */
    schedulerMode?: ExFlowSchedulerMode;
    /**
     * Fallback deterministic tie policy when priority/deadline/weight/tieBreaker are equal.
     * Defaults to `insertion`.
     */
    tieFallbackPolicy?: ExFlowTieFallbackPolicy;
    /**
     * Fairness strategy for constrained scheduling rounds.
     * `aging` prioritizes nodes that have been deferred repeatedly.
     */
    fairnessPolicy?: ExFlowFairnessPolicy;
    /**
     * Nodes deferred for at least this many rounds receive maximum fairness priority.
     */
    maxDeferralRounds?: number;
    /**
     * When true, every node.resourceClass must have a corresponding resourceCaps entry.
     */
    requireResourceCapForAllClasses?: boolean;
    /**
     * Optional named preset for common enterprise scheduling profiles.
     */
    presetName?: ExFlowPresetName;
}
/**
 * The resulting item shape returned by ExFlow.
 * `exFlowPriority` is metadata injected by ExFlow and must not exist in input data.
 */
type ExFlowResultItem<T extends object & ExFlowSafeData> = Omit<T, "exFlowPriority"> & {
    exFlowPriority: number;
};
/**
 * Clone behavior depends on ExFlow options:
 * - shallow (default): nested objects inside `data` keep original references.
 * - deep: nested objects are fully cloned.
 * - custom: cloning behavior is controlled by user-provided cloneFn.
 */
interface ExecutionPlan<T extends object & ExFlowSafeData> {
    batches: ExFlowResultItem<T>[][];
    fullSequence: ExFlowResultItem<T>[];
}

interface ExFlowDiagnostics {
    cyclePath?: string[];
    unresolvedNodeIds?: string[];
    invalidOptionField?: string;
    invalidOptionValue?: unknown;
    details?: string;
}
interface ExFlowMetrics {
    schedulerMode: ExFlowSchedulerMode;
    rounds: number;
    emittedNodes: number;
    deferredNodes: number;
    maxReadyQueueSize: number;
    constraintHits: {
        concurrencyCap: number;
        resourceCaps: number;
    };
}
interface ExFlowExecutionDetails<T extends object & ExFlowSafeData> {
    plan: ExecutionPlan<T>;
    metrics: ExFlowMetrics;
}
interface ExFlowObservabilityEvent {
    source: "ex-flow";
    code?: string;
    message: string;
    name: string;
    diagnostics?: ExFlowDiagnostics;
    timestamp: string;
}
type ExFlowOpenTelemetryAttributes = Record<string, string | number | boolean>;
type ExFlowDatadogLogFields = Record<string, string | number | boolean | null>;
type ExFlowCustomMappedFields = Record<string, string | number | boolean | null>;
interface ExFlowDiagnosticsMapperOptions {
    keyPrefix?: string;
    separator?: "." | "_" | "-";
    fieldNameMap?: Partial<Record<"source" | "code" | "message" | "name" | "timestamp" | "cyclePath" | "unresolvedNodeIds" | "invalidOptionField" | "invalidOptionValue" | "details", string>>;
    staticFields?: ExFlowCustomMappedFields;
    includeNulls?: boolean;
    valueTransform?: (value: unknown, key: string, event: ExFlowObservabilityEvent) => unknown;
}

export type { DeadlineStrategy, ExFlowCloneMode, ExFlowCustomMappedFields, ExFlowDatadogLogFields, ExFlowDiagnostics, ExFlowDiagnosticsMapperOptions, ExFlowExecutionDetails, ExFlowFairnessPolicy, ExFlowMetrics, ExFlowObservabilityEvent, ExFlowOpenTelemetryAttributes, ExFlowOptions, ExFlowPresetName, ExFlowResultItem, ExFlowSafeData, ExFlowSchedulerMode, ExFlowTieBreaker, ExFlowTieFallbackPolicy, ExNode, ExecutionPlan, SafeTask, WeightStrategy };